@_nazmiforreal/flutter-ota 0.1.0 → 0.1.2

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

@@ -0,0 +1,111 @@
+import 'changed_asset.dart' show ChangedAsset;
+import 'status.dart';
+
+/// hot-updater `UpdateInfo` — database-layer update decision.
+class UpdateInfo {
+  final String id;
+  final bool shouldForceUpdate;
+  final String? message;
+  final UpdateStatus status;
+  final String? storageUri;
+  final String? fileHash;
+
+  /// Internal rollout metadata; never serialized to update-check clients.
+  final int? rolloutCohortCount;
+  final List<String>? targetCohorts;
+
+  const UpdateInfo({
+    required this.id,
+    required this.shouldForceUpdate,
+    required this.message,
+    required this.status,
+    required this.storageUri,
+    required this.fileHash,
+    this.rolloutCohortCount,
+    this.targetCohorts,
+  });
+}
+
+/// Device-facing payload for an available update —
+/// hot-updater `AppUpdateAvailableInfo`.
+class AppUpdateAvailableInfo extends AppUpdateInfo {
+  final String id;
+  final bool shouldForceUpdate;
+  final String? message;
+  final UpdateStatus status;
+  final String? fileUrl;
+  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;
+
+  final String? manifestUrl;
+  final String? manifestFileHash;
+  final Map<String, ChangedAsset>? changedAssets;
+
+  const AppUpdateAvailableInfo({
+    required this.id,
+    required this.shouldForceUpdate,
+    required this.message,
+    required this.status,
+    required this.fileUrl,
+    required this.fileHash,
+    this.signature,
+    this.manifestUrl,
+    this.manifestFileHash,
+    this.changedAssets,
+  });
+
+  factory AppUpdateAvailableInfo.fromJson(Map<String, dynamic> j) =>
+      AppUpdateAvailableInfo(
+        id: j['id'] as String,
+        shouldForceUpdate: (j['shouldForceUpdate'] ?? false) as bool,
+        message: j['message'] as String?,
+        status: UpdateStatus.fromValue(j['status'] as String),
+        fileUrl: j['fileUrl'] as String?,
+        fileHash: j['fileHash'] as String?,
+        signature: j['signature'] as String?,
+        manifestUrl: j['manifestUrl'] as String?,
+        manifestFileHash: j['manifestFileHash'] as String?,
+        changedAssets: (j['changedAssets'] as Map?)?.map((k, v) => MapEntry(
+              k as String,
+              ChangedAsset.fromJson((v as Map).cast<String, dynamic>()),
+            )),
+      );
+
+  @override
+  Map<String, dynamic> toJson() => {
+        'id': id,
+        'shouldForceUpdate': shouldForceUpdate,
+        'message': message,
+        'status': status.value,
+        'fileUrl': fileUrl,
+        'fileHash': fileHash,
+        if (signature != null) 'signature': signature,
+        if (manifestUrl != null) 'manifestUrl': manifestUrl,
+        if (manifestFileHash != null) 'manifestFileHash': manifestFileHash,
+        if (changedAssets != null) 'changedAssets': changedAssets,
+      };
+}
+
+/// Device-facing "nothing to do" — hot-updater `AppUpToDateInfo`.
+class AppUpToDateInfo extends AppUpdateInfo {
+  const AppUpToDateInfo();
+
+  @override
+  Map<String, dynamic> toJson() => {'status': 'UP_TO_DATE'};
+}
+
+/// Sealed union: hot-updater `AppUpdateInfo`.
+sealed class AppUpdateInfo {
+  const AppUpdateInfo();
+
+  Map<String, dynamic> toJson();
+
+  factory AppUpdateInfo.fromJson(Map<String, dynamic> j) {
+    final raw = j['status'];
+    if (raw == 'UP_TO_DATE') return const AppUpToDateInfo();
+    return AppUpdateAvailableInfo.fromJson(j);
+  }
+}

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

@@ -0,0 +1,191 @@
+import 'metadata.dart';
+import 'bundle_patch_artifact.dart';
+import 'platform.dart';
+import 'uuid.dart' show nilUuid;
+
+/// hot-updater `Bundle` — the central database row / manifest object.
+///
+/// Wire format is camelCase; database rows are snake_case. [Bundle.fromJson]
+/// tolerates both so one model works against PostgREST rows and API payloads.
+class Bundle {
+  final String id; // uuidv7
+
+  final Platform platform;
+  final bool shouldForceUpdate;
+  final bool enabled;
+
+  /// MD5 hex of the artifact blob. The device SDK verifies the downloaded
+  /// file against this value (see [SignatureVerifier]). When the bundle is
+  /// signed, the Ed25519 signature lives in [BundleMetadata.signature]
+  /// (carried in the update-check `signature` field), not here.
+  final String fileHash;
+
+  /// Protocol URI, e.g. supabase-storage://bucket/bundles/<id>/patch.zip.
+  final String storageUri;
+  final String? gitCommitHash;
+  final String? message;
+
+  /// Default "production".
+  final String channel;
+
+  /// Semver range; XOR with [fingerprintHash] per DB CHECK constraint.
+  final String? targetAppVersion;
+  final String? fingerprintHash;
+  final BundleMetadata? metadata;
+  final String? manifestStorageUri;
+  final String? manifestFileHash;
+  final String? assetBaseStorageUri;
+
+  /// Binary patch artifacts, array order = precedence.
+  final List<BundlePatchArtifact>? patches;
+
+  // Deprecated single-patch fields (kept for wire compatibility).
+  final String? patchBaseBundleId;
+  final String? patchBaseFileHash;
+  final String? patchFileHashLegacy;
+  final String? patchStorageUri;
+
+  /// Per-mille 0..1000; null = full rollout.
+  final int? rolloutCohortCount;
+
+  /// Stored in DB, never returned to update-check clients.
+  final List<String>? targetCohorts;
+
+  const Bundle({
+    required this.id,
+    required this.platform,
+    required this.shouldForceUpdate,
+    required this.enabled,
+    required this.fileHash,
+    required this.storageUri,
+    required this.channel,
+    this.gitCommitHash,
+    this.message,
+    this.targetAppVersion,
+    this.fingerprintHash,
+    this.metadata,
+    this.manifestStorageUri,
+    this.manifestFileHash,
+    this.assetBaseStorageUri,
+    this.patches,
+    this.patchBaseBundleId,
+    this.patchBaseFileHash,
+    String? patchFileHash,
+    this.patchStorageUri,
+    this.rolloutCohortCount,
+    this.targetCohorts,
+  }) : patchFileHashLegacy = patchFileHash;
+
+  static T? _s<T>(Map<String, dynamic> j, String camel, String snake) {
+    final v = j[camel] ?? j[snake];
+    return v == null ? null : v as T;
+  }
+
+  factory Bundle.fromJson(Map<String, dynamic> j) => Bundle(
+        id: (j['id'] ?? nilUuid) as String,
+        platform: Platform.fromValue(j['platform'] as String),
+        shouldForceUpdate:
+            (j['shouldForceUpdate'] ?? j['should_force_update'] ?? false)
+                as bool,
+        enabled: (j['enabled'] ?? false) as bool,
+        fileHash: (j['fileHash'] ?? j['file_hash']) as String,
+        storageUri: (j['storageUri'] ?? j['storage_uri']) as String,
+        gitCommitHash: _s<String>(j, 'gitCommitHash', 'git_commit_hash'),
+        message: j['message'] == null ? null : j['message'] as String,
+        channel: (j['channel'] ?? 'production') as String,
+        targetAppVersion:
+            _s<String>(j, 'targetAppVersion', 'target_app_version'),
+        fingerprintHash: _s<String>(j, 'fingerprintHash', 'fingerprint_hash'),
+        metadata: j['metadata'] is Map
+            ? BundleMetadata.fromJson(
+                (j['metadata'] as Map).cast<String, dynamic>())
+            : null,
+        manifestStorageUri:
+            _s<String>(j, 'manifestStorageUri', 'manifest_storage_uri'),
+        manifestFileHash:
+            _s<String>(j, 'manifestFileHash', 'manifest_file_hash'),
+        assetBaseStorageUri:
+            _s<String>(j, 'assetBaseStorageUri', 'asset_base_storage_uri'),
+        patches: (j['patches'] as List?)
+            ?.map((e) =>
+                BundlePatchArtifact.fromJson((e as Map).cast<String, dynamic>()))
+            .toList(),
+        patchBaseBundleId:
+            _s<String>(j, 'patchBaseBundleId', 'patch_base_bundle_id'),
+        patchBaseFileHash:
+            _s<String>(j, 'patchBaseFileHash', 'patch_base_file_hash'),
+        patchFileHash: _s(j, 'patchFileHash', 'patch_file_hash'),
+        patchStorageUri: _s<String>(j, 'patchStorageUri', 'patch_storage_uri'),
+        rolloutCohortCount:
+            _s<int>(j, 'rolloutCohortCount', 'rollout_cohort_count'),
+        targetCohorts:
+            (j['targetCohorts'] as List? ?? j['target_cohorts'] as List?)
+                ?.map((e) => e as String)
+                .toList(),
+      );
+
+  /// camelCase wire format (server API payloads).
+  Map<String, dynamic> toJson() => {
+        'id': id,
+        'platform': platform.value,
+        'shouldForceUpdate': shouldForceUpdate,
+        'enabled': enabled,
+        'fileHash': fileHash,
+        'storageUri': storageUri,
+        if (gitCommitHash != null) 'gitCommitHash': gitCommitHash,
+        if (message != null) 'message': message,
+        'channel': channel,
+        if (targetAppVersion != null) 'targetAppVersion': targetAppVersion,
+        if (fingerprintHash != null) 'fingerprintHash': fingerprintHash,
+        if (metadata != null) 'metadata': metadata!.toJson(),
+        if (manifestStorageUri != null)
+          'manifestStorageUri': manifestStorageUri,
+        if (manifestFileHash != null) 'manifestFileHash': manifestFileHash,
+        if (assetBaseStorageUri != null)
+          'assetBaseStorageUri': assetBaseStorageUri,
+        if (patches != null)
+          'patches': patches!.map((p) => p.toJson()).toList(),
+        if (patchBaseBundleId != null) 'patchBaseBundleId': patchBaseBundleId,
+        if (patchBaseFileHash != null)
+          'patchBaseFileHash': patchBaseFileHash,
+        if (patchFileHashLegacy != null)
+          'patchFileHash': patchFileHashLegacy,
+        if (patchStorageUri != null) 'patchStorageUri': patchStorageUri,
+        if (rolloutCohortCount != null)
+          'rolloutCohortCount': rolloutCohortCount,
+        if (targetCohorts != null) 'targetCohorts': targetCohorts,
+      };
+
+  /// snake_case row format (Postgres/Supabase columns).
+  Map<String, dynamic> toSqlJson() => {
+        'id': id,
+        'platform': platform.value,
+        'should_force_update': shouldForceUpdate,
+        '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,
+      };
+
+  @override
+  bool operator ==(Object o) =>
+      o is Bundle && o.toJson().toString() == toJson().toString();
+
+  @override
+  int get hashCode => toJson().toString().hashCode;
+}

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

@@ -0,0 +1,39 @@
+/// Faithful port of hot-updater `packages/core/src/bundleArtifacts.ts`.
+///
+/// Utility functions for reading and normalizing bundle patch metadata
+/// from the flexible `Bundle` / `BundlePatchArtifact` shape.
+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.)
+Map<String, Object?>? stripBundleArtifactMetadata(
+  Map<String, Object?>? metadata,
+) =>
+    metadata;
+
+/// Extract `manifestStorageUri` from a bundle, defaulting to null.
+String? getManifestStorageUri(Bundle bundle) => bundle.manifestStorageUri;
+
+/// Extract `manifestFileHash` from a bundle, defaulting to null.
+String? getManifestFileHash(Bundle bundle) => bundle.manifestFileHash;
+
+/// Extract `assetBaseStorageUri` from a bundle, defaulting to null.
+String? getAssetBaseStorageUri(Bundle bundle) => bundle.assetBaseStorageUri;
+
+/// Deduplicate patches by [BundlePatchArtifact.baseBundleId], keeping the
+/// first occurrence (by insertion order).
+List<BundlePatchArtifact> getBundlePatches(Bundle bundle) {
+  final patches = bundle.patches;
+  if (patches == null || patches.isEmpty) return const [];
+
+  final seenBaseBundleIds = <String>{};
+  return patches.where((patch) {
+    if (seenBaseBundleIds.contains(patch.baseBundleId)) return false;
+    seenBaseBundleIds.add(patch.baseBundleId);
+    return true;
+  }).toList();
+}

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

@@ -0,0 +1,47 @@
+/// Binary patch artifact — hot-updater `BundlePatchArtifact`.
+library;
+
+class BundlePatchArtifact {
+  final String baseBundleId;
+  final String baseFileHash;
+  final String patchFileHash;
+  final String patchStorageUri;
+
+  const BundlePatchArtifact({
+    required this.baseBundleId,
+    required this.baseFileHash,
+    required this.patchFileHash,
+    required this.patchStorageUri,
+  });
+
+  factory BundlePatchArtifact.fromJson(Map<String, dynamic> j) =>
+      BundlePatchArtifact(
+        baseBundleId:
+            j['baseBundleId'] as String? ?? j['base_bundle_id'] as String,
+        baseFileHash:
+            j['baseFileHash'] as String? ?? j['base_file_hash'] as String,
+        patchFileHash:
+            j['patchFileHash'] as String? ?? j['patch_file_hash'] as String,
+        patchStorageUri: j['patchStorageUri'] as String? ??
+            j['patch_storage_uri'] as String,
+      );
+
+  Map<String, dynamic> toJson() => {
+        'baseBundleId': baseBundleId,
+        'baseFileHash': baseFileHash,
+        'patchFileHash': patchFileHash,
+        'patchStorageUri': patchStorageUri,
+      };
+
+  @override
+  bool operator ==(Object o) =>
+      o is BundlePatchArtifact &&
+      o.baseBundleId == baseBundleId &&
+      o.baseFileHash == baseFileHash &&
+      o.patchFileHash == patchFileHash &&
+      o.patchStorageUri == patchStorageUri;
+
+  @override
+  int get hashCode =>
+      Object.hash(baseBundleId, baseFileHash, patchFileHash, patchStorageUri);
+}

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

@@ -0,0 +1,77 @@
+/// Per-asset diff descriptors — hot-updater `ChangedAsset*`.
+library;
+
+class ChangedAssetFile {
+  /// "br" or null.
+  final String? compression;
+  final String url;
+
+  const ChangedAssetFile({required this.url, this.compression});
+
+  factory ChangedAssetFile.fromJson(Map<String, dynamic> j) =>
+      ChangedAssetFile(url: j['url'] as String, compression: j['compression'] as String?);
+
+  Map<String, dynamic> toJson() => {'url': url, 'compression': compression};
+}
+
+class ChangedAssetPatch {
+  final String baseBundleId;
+  final String baseFileHash;
+  final String patchFileHash;
+  final String patchUrl;
+
+  /// Always "bsdiff" in hot-updater; kept for wire compatibility.
+  final String algorithm;
+
+  const ChangedAssetPatch({
+    required this.baseBundleId,
+    required this.baseFileHash,
+    required this.patchFileHash,
+    required this.patchUrl,
+    this.algorithm = 'bsdiff',
+  });
+
+  factory ChangedAssetPatch.fromJson(Map<String, dynamic> j) =>
+      ChangedAssetPatch(
+        baseBundleId: j['baseBundleId'] as String,
+        baseFileHash: j['baseFileHash'] as String,
+        patchFileHash: j['patchFileHash'] as String,
+        patchUrl: j['patchUrl'] as String,
+        algorithm: j['algorithm'] as String? ?? 'bsdiff',
+      );
+
+  Map<String, dynamic> toJson() => {
+        'algorithm': algorithm,
+        'baseBundleId': baseBundleId,
+        'baseFileHash': baseFileHash,
+        'patchFileHash': patchFileHash,
+        'patchUrl': patchUrl,
+      };
+}
+
+class ChangedAsset {
+  /// SHA256 hex of the asset file.
+  final String fileHash;
+  final ChangedAssetFile? file;
+  final ChangedAssetPatch? patch;
+
+  const ChangedAsset({required this.fileHash, this.file, this.patch});
+
+  factory ChangedAsset.fromJson(Map<String, dynamic> j) => ChangedAsset(
+        fileHash: j['fileHash'] as String,
+        file: j['file'] == null
+            ? null
+            : ChangedAssetFile.fromJson(
+                (j['file'] as Map).cast<String, dynamic>()),
+        patch: j['patch'] == null
+            ? null
+            : ChangedAssetPatch.fromJson(
+                (j['patch'] as Map).cast<String, dynamic>()),
+      );
+
+  Map<String, dynamic> toJson() => {
+        'fileHash': fileHash,
+        'file': file?.toJson(),
+        'patch': patch?.toJson(),
+      };
+}

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

@@ -0,0 +1,78 @@
+import 'platform.dart';
+import 'strategy.dart';
+import 'uuid.dart' show nilUuid;
+
+/// hot-updater `GetBundlesArgs` — update-check request parameters.
+///
+/// Two variants keyed by [UpdateStrategy]; shared fields defaulted the same
+/// way (minBundleId = NIL_UUID, channel = "production").
+sealed class GetBundlesArgs {
+  final UpdateStrategy _updateStrategy;
+  final Platform platform;
+  final String bundleId;
+  final String minBundleId;
+  final String channel;
+
+  /// Cohort identifier for server-side rollout decisions.
+  final String? cohort;
+
+  const GetBundlesArgs({
+    required UpdateStrategy strategy,
+    required this.platform,
+    required this.bundleId,
+    this.minBundleId = nilUuid,
+    this.channel = 'production',
+    this.cohort,
+  }) : _updateStrategy = strategy;
+
+  /// Public accessor for the resolved update strategy.
+  UpdateStrategy get updateStrategy => _updateStrategy;
+
+  Map<String, dynamic> toJson() => {
+        '_updateStrategy': _updateStrategy.value,
+        'platform': platform.value,
+        'bundleId': bundleId,
+        if (minBundleId != nilUuid) 'minBundleId': minBundleId,
+        if (channel != 'production') 'channel': channel,
+        if (cohort != null) 'cohort': cohort,
+      };
+}
+
+class FingerprintGetBundlesArgs extends GetBundlesArgs {
+  final String fingerprintHash;
+
+  const FingerprintGetBundlesArgs({
+    required super.platform,
+    required super.bundleId,
+    super.minBundleId,
+    super.channel,
+    super.cohort,
+    required this.fingerprintHash,
+  }) : super(strategy: UpdateStrategy.fingerprint);
+
+  @override
+  Map<String, dynamic> toJson() => {
+        ...super.toJson(),
+        'fingerprintHash': fingerprintHash,
+      };
+}
+
+class AppVersionGetBundlesArgs extends GetBundlesArgs {
+  /// Current app version (semver).
+  final String appVersion;
+
+  const AppVersionGetBundlesArgs({
+    required super.platform,
+    required super.bundleId,
+    super.minBundleId,
+    super.channel,
+    super.cohort,
+    required this.appVersion,
+  }) : super(strategy: UpdateStrategy.appVersion);
+
+  @override
+  Map<String, dynamic> toJson() => {
+        ...super.toJson(),
+        'appVersion': appVersion,
+      };
+}

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

@@ -0,0 +1,31 @@
+/// Bundle metadata — hot-updater `BundleMetadata` (snake_case on the wire).
+library;
+
+class BundleMetadata {
+  final String? appVersion;
+
+  /// Ed25519 (base64) signature over the artifact's MD5 hex string. Stored here
+  /// (rather than a dedicated column) so it round-trips through every backend's
+  /// JSON `metadata` column without a schema migration. The device SDK reads
+  /// this to verify the patch (see [AppUpdateAvailableInfo.signature]).
+  final String? signature;
+
+  const BundleMetadata({this.appVersion, this.signature});
+
+  factory BundleMetadata.fromJson(Map<String, dynamic> j) => BundleMetadata(
+        appVersion: j['app_version'] as String?,
+        signature: j['signature'] as String?,
+      );
+
+  Map<String, dynamic> toJson() => {
+        'app_version': appVersion,
+        if (signature != null) 'signature': signature,
+      };
+
+  @override
+  bool operator ==(Object o) =>
+      o is BundleMetadata && o.appVersion == appVersion && o.signature == signature;
+
+  @override
+  int get hashCode => Object.hash(appVersion, signature);
+}