chore(shorebird_code_push_protocol): Add metadata messages (#1823)

packages/shorebird_code_push_client/lib/src/code_push_client.dart

@@ -253,6 +253,8 @@ class CodePushClient {
       wasForced: false,
       hasAssetChanges: hasAssetChanges,
       hasNativeChanges: hasNativeChanges,
+      // TODO(bryanoltman): add metadata
+      metadata: null,
     );
     final response = await _httpClient.post(
       Uri.parse('$_v1/apps/$appId/patches'),
@@ -304,6 +306,8 @@ class CodePushClient {
         UpdateReleaseRequest(
           status: status,
           platform: platform,
+          // TODO(bryanoltman): add metadata
+          metadata: null,
         ).toJson(),
       ),
     );

packages/shorebird_code_push_protocol/lib/src/messages/create_patch/create_patch_request.dart

@@ -1,4 +1,5 @@
 import 'package:json_annotation/json_annotation.dart';
+import 'package:shorebird_code_push_protocol/src/models/create_patch_metadata.dart';
 
 part 'create_patch_request.g.dart';
 
@@ -13,6 +14,7 @@ class CreatePatchRequest {
     required this.wasForced,
     required this.hasAssetChanges,
     required this.hasNativeChanges,
+    required this.metadata,
   });
 
   /// Converts a Map<String, dynamic> to a [CreatePatchRequest]
@@ -29,8 +31,13 @@ class CreatePatchRequest {
   final bool? wasForced;
 
   /// Whether the patch's assets were not the same as those of the release
+  // TODO(bryanoltman): remove this after metadata change is fully rolled out.
   final bool? hasAssetChanges;
 
   /// Whether the patch's native code is different than that of the release.
+  // TODO(bryanoltman): remove this after metadata change is fully rolled out.
   final bool? hasNativeChanges;
+
+  /// Additional information about the creation of the patch.
+  final CreatePatchMetadata? metadata;
 }

packages/shorebird_code_push_protocol/lib/src/messages/update_release/update_release_request.dart

@@ -12,6 +12,7 @@ class UpdateReleaseRequest {
   const UpdateReleaseRequest({
     required this.status,
     required this.platform,
+    required this.metadata,
   });
 
   /// Converts a Map<String, dynamic> to a [UpdateReleaseRequest].
@@ -26,4 +27,7 @@ class UpdateReleaseRequest {
 
   /// The platform of the release.
   final ReleasePlatform platform;
+
+  /// Additional information about the release.
+  final UpdateReleaseMetadata? metadata;
 }

packages/shorebird_code_push_protocol/lib/src/models/build_environment_metadata.dart

@@ -0,0 +1,82 @@
+import 'package:equatable/equatable.dart';
+import 'package:json_annotation/json_annotation.dart';
+
+part 'build_environment_metadata.g.dart';
+
+/// {@template build_environment_metadata}
+/// Information about the environment used to build a release or patch.
+///
+/// Collection of this information is done to help Shorebird users debug any
+/// later failures in their builds.
+///
+/// We do not collect Personally Identifying Information (e.g. no paths,
+/// argument lists, etc.) in accordance with our privacy policy:
+/// https://shorebird.dev/privacy/
+/// {@endtemplate}
+@JsonSerializable()
+class BuildEnvironmentMetadata extends Equatable {
+  /// {@macro build_environment_metadata}
+  const BuildEnvironmentMetadata({
+    required this.shorebirdVersion,
+    required this.operatingSystem,
+    required this.operatingSystemVersion,
+    required this.xcodeVersion,
+  });
+
+  /// coverage:ignore-start
+  /// Creates a [BuildEnvironmentMetadata] with overridable default values for
+  /// testing purposes.
+  factory BuildEnvironmentMetadata.forTest({
+    String shorebirdVersion = '4.5.6',
+    String operatingSystem = 'macos',
+    String operatingSystemVersion = '1.2.3',
+    String? xcodeVersion = '15.0',
+  }) =>
+      BuildEnvironmentMetadata(
+        shorebirdVersion: shorebirdVersion,
+        operatingSystem: operatingSystem,
+        operatingSystemVersion: operatingSystemVersion,
+        xcodeVersion: xcodeVersion,
+      );
+  // coverage:ignore-end
+
+  /// Converts a Map<String, dynamic> to a [BuildEnvironmentMetadata]
+  factory BuildEnvironmentMetadata.fromJson(Map<String, dynamic> json) =>
+      _$BuildEnvironmentMetadataFromJson(json);
+
+  /// Converts a [BuildEnvironmentMetadata] to a Map<String, dynamic>
+  Map<String, dynamic> toJson() => _$BuildEnvironmentMetadataToJson(this);
+
+  /// The version of Shorebird used to run the command.
+  ///
+  /// Reason: each version of shorebird has new features and bug fixes. Users
+  /// using an older version may be running into issues that have already been
+  /// fixed.
+  final String shorebirdVersion;
+
+  /// The operating system used to run the release command.
+  ///
+  /// Reason: issues may occur on some OSes and not others (especially Windows
+  /// vs non-Windows).
+  final String operatingSystem;
+
+  /// The version of [operatingSystem].
+  ///
+  /// Reason: issues may occur on some OS versions and not others.
+  final String operatingSystemVersion;
+
+  /// The version of Xcode used to build the patch. Only provided for iOS
+  /// patches.
+  ///
+  /// Reason: Xcode behavior can change between versions. Ex: the
+  /// `shorebird preview` mechanism changed entirely between Xcode 14 and 15.
+  final String? xcodeVersion;
+
+  @override
+  List<Object?> get props => [
+        shorebirdVersion,
+        operatingSystem,
+        operatingSystemVersion,
+        xcodeVersion,
+      ];
+}

packages/shorebird_code_push_protocol/lib/src/models/create_patch_metadata.dart

@@ -0,0 +1,100 @@
+import 'package:equatable/equatable.dart';
+import 'package:json_annotation/json_annotation.dart';
+import 'package:shorebird_code_push_protocol/src/models/models.dart';
+
+part 'create_patch_metadata.g.dart';
+
+/// {@template create_patch_metadata}
+/// Information about a patch, used for debugging purposes.
+///
+/// Collection of this information is done to help Shorebird users debug any
+/// later failures in their builds.
+///
+/// We do not collect Personally Identifying Information (e.g. no paths,
+/// argument lists, etc.) in accordance with our privacy policy:
+/// https://shorebird.dev/privacy/
+/// {@endtemplate}
+@JsonSerializable()
+class CreatePatchMetadata extends Equatable {
+  /// {@macro create_patch_metadata}
+  const CreatePatchMetadata({
+    required this.releasePlatform,
+    required this.usedIgnoreAssetChangesFlag,
+    required this.hasAssetChanges,
+    required this.usedIgnoreNativeChangesFlag,
+    required this.hasNativeChanges,
+    required this.environment,
+  });
+
+  // coverage:ignore-start
+  /// Creates a [CreatePatchMetadata] with overridable default values for
+  /// testing purposes.
+  factory CreatePatchMetadata.forTest({
+    ReleasePlatform releasePlatform = ReleasePlatform.android,
+    bool usedIgnoreAssetChangesFlag = false,
+    bool hasAssetChanges = false,
+    bool usedIgnoreNativeChangesFlag = false,
+    bool hasNativeChanges = false,
+    BuildEnvironmentMetadata? environment,
+  }) =>
+      CreatePatchMetadata(
+        releasePlatform: releasePlatform,
+        usedIgnoreAssetChangesFlag: usedIgnoreAssetChangesFlag,
+        hasAssetChanges: hasAssetChanges,
+        usedIgnoreNativeChangesFlag: usedIgnoreNativeChangesFlag,
+        hasNativeChanges: hasNativeChanges,
+        environment: environment ?? BuildEnvironmentMetadata.forTest(),
+      );
+  // coverage:ignore-end
+
+  /// Converts a Map<String, dynamic> to a [CreatePatchMetadata]
+  factory CreatePatchMetadata.fromJson(Map<String, dynamic> json) =>
+      _$CreatePatchMetadataFromJson(json);
+
+  /// Converts a [CreatePatchMetadata] to a Map<String, dynamic>
+  Map<String, dynamic> toJson() => _$CreatePatchMetadataToJson(this);
+
+  /// The platform for which the patch was created.
+  final ReleasePlatform releasePlatform;
+
+  /// Whether the `--allow-asset-diffs` flag was used.
+  ///
+  /// Reason: this helps us understand how often prevalent the need to ignore
+  /// asset changes is.
+  final bool usedIgnoreAssetChangesFlag;
+
+  /// Whether asset changes were detected in the patch.
+  ///
+  /// Reason: shorebird does not support asset changes in patches, and knowing
+  /// that asset changes were detected can help explain unexpected behavior in
+  /// a patch.
+  final bool hasAssetChanges;
+
+  /// Whether the `--allow-native-diffs` flag was used.
+  ///
+  /// Reason: this helps us understand how often prevalent the need to ignore
+  /// native code changes is.
+  final bool usedIgnoreNativeChangesFlag;
+
+  /// Whether native code changes were detected in the patch.
+  ///
+  /// Reason: shorebird does not support native code changes in patches, and
+  /// knowing that native code changes were detected can help explain unexpected
+  /// behavior in a patch.
+  final bool hasNativeChanges;
+
+  /// Properties about the environment in which the patch was created.
+  ///
+  /// Reason: see [BuildEnvironmentMetadata].
+  final BuildEnvironmentMetadata environment;
+
+  @override
+  List<Object?> get props => [
+        releasePlatform,
+        usedIgnoreAssetChangesFlag,
+        hasAssetChanges,
+        usedIgnoreNativeChangesFlag,
+        hasNativeChanges,
+        environment,
+      ];
+}