feat: API V3 now supported for "get product"

example/lib/main.dart

@@ -1,18 +1,24 @@
 import 'dart:async';
 
 import 'package:openfoodfacts/model/OcrIngredientsResult.dart';
+import 'package:openfoodfacts/model/ProductResultV3.dart';
 import 'package:openfoodfacts/openfoodfacts.dart';
 import 'package:openfoodfacts/utils/TagType.dart';
 
 /// request a product from the OpenFoodFacts database
 Future<Product?> getProduct() async {
   var barcode = '0048151623426';
 
-  ProductQueryConfiguration configuration = ProductQueryConfiguration(barcode,
-      language: OpenFoodFactsLanguage.GERMAN, fields: [ProductField.ALL]);
-  ProductResult result = await OpenFoodAPIClient.getProduct(configuration);
+  final ProductQueryConfiguration configuration = ProductQueryConfiguration(
+    barcode,
+    language: OpenFoodFactsLanguage.GERMAN,
+    fields: [ProductField.ALL],
+    version: ProductQueryVersion.v3,
+  );
+  final ProductResultV3 result =
+      await OpenFoodAPIClient.getProductV3(configuration);
 
-  if (result.status == 1) {
+  if (result.status == ProductResultV3.statusSuccess) {
     return result.product;
   } else {
     throw Exception('product not found, please insert data for $barcode');
@@ -120,16 +126,20 @@ void saveAndExtractIngredient() async {
   }
 
   //Get The saved product's ingredients from the server
-  ProductQueryConfiguration configurations = ProductQueryConfiguration(
-      '3613042717385',
-      language: OpenFoodFactsLanguage.FRENCH,
-      fields: [
-        ProductField.INGREDIENTS_TEXT,
-      ]);
-  ProductResult productResult =
-      await OpenFoodAPIClient.getProduct(configurations, user: myUser);
-
-  if (productResult.status != 1) {
+  final ProductQueryConfiguration configurations = ProductQueryConfiguration(
+    '3613042717385',
+    language: OpenFoodFactsLanguage.FRENCH,
+    fields: [
+      ProductField.INGREDIENTS_TEXT,
+    ],
+    version: ProductQueryVersion.v3,
+  );
+  final ProductResultV3 productResult = await OpenFoodAPIClient.getProductV3(
+    configurations,
+    user: myUser,
+  );
+
+  if (productResult.status != ProductResultV3.statusSuccess) {
     throw Exception('product not found, please insert data for 3613042717385');
   }
 }

lib/model/LocalizedTag.dart

@@ -0,0 +1,35 @@
+import 'package:json_annotation/json_annotation.dart';
+import '../interface/JsonObject.dart';
+
+part 'LocalizedTag.g.dart';
+
+/// Tag with localizations (in English and an additional language).
+///
+/// We need to populate URL parameter `tag_lc` to get [lcName].
+@JsonSerializable()
+class LocalizedTag extends JsonObject {
+  /// Tag id.
+  @JsonKey(includeIfNull: false)
+  String? id;
+
+  /// Name in English.
+  @JsonKey(includeIfNull: false)
+  String? name;
+
+  /// Localized name - according to query parameter `tags_lc`.
+  @JsonKey(name: 'lc_name', includeIfNull: false)
+  String? lcName;
+
+  LocalizedTag();
+
+  factory LocalizedTag.fromJson(Map<String, dynamic> json) =>
+      _$LocalizedTagFromJson(json);
+
+  @override
+  Map<String, dynamic> toJson() => _$LocalizedTagToJson(this);
+
+  Map<String, String> toServerData() => JsonObject.toDataStatic(toJson());
+
+  @override
+  String toString() => toServerData().toString();
+}

lib/model/ProductResult.dart

@@ -4,6 +4,8 @@ import 'Product.dart';
 
 part 'ProductResult.g.dart';
 
+// TODO: deprecated from 2022-12-01; remove when old enough
+@Deprecated('Use ProductResultV3 instead')
 @JsonSerializable()
 class ProductResult extends JsonObject {
   final int? status;

lib/model/ProductResultField.dart

@@ -0,0 +1,28 @@
+import 'package:json_annotation/json_annotation.dart';
+import '../interface/JsonObject.dart';
+
+part 'ProductResultField.g.dart';
+
+/// Field part of an API V3 answer.
+@JsonSerializable()
+class ProductResultField extends JsonObject {
+  ProductResultField();
+
+  @JsonKey(includeIfNull: false)
+  String? id;
+
+  @JsonKey(includeIfNull: false)
+  String? value;
+
+  @JsonKey(name: 'default_value', includeIfNull: false)
+  String? defaultValue;
+
+  factory ProductResultField.fromJson(Map<String, dynamic> json) =>
+      _$ProductResultFieldFromJson(json);
+
+  @override
+  Map<String, dynamic> toJson() => _$ProductResultFieldToJson(this);
+
+  @override
+  String toString() => toJson().toString();
+}

lib/model/ProductResultFieldAnswer.dart

@@ -0,0 +1,33 @@
+import 'package:json_annotation/json_annotation.dart';
+import 'package:openfoodfacts/interface/JsonObject.dart';
+import 'package:openfoodfacts/model/LocalizedTag.dart';
+import 'package:openfoodfacts/model/ProductResultField.dart';
+
+part 'ProductResultFieldAnswer.g.dart';
+
+/// API V3 answer for one field.
+@JsonSerializable()
+class ProductResultFieldAnswer extends JsonObject {
+  ProductResultFieldAnswer();
+
+  /// Field on which there is a specific answer.
+  @JsonKey(includeIfNull: false)
+  ProductResultField? field;
+
+  /// Impact, e.g. "Field ignored".
+  @JsonKey(includeIfNull: false)
+  LocalizedTag? impact;
+
+  /// Message, e.g. "Missing field".
+  @JsonKey(includeIfNull: false)
+  LocalizedTag? message;
+
+  factory ProductResultFieldAnswer.fromJson(Map<String, dynamic> json) =>
+      _$ProductResultFieldAnswerFromJson(json);
+
+  @override
+  Map<String, dynamic> toJson() => _$ProductResultFieldAnswerToJson(this);
+
+  @override
+  String toString() => toJson().toString();
+}

lib/model/ProductResultV3.dart

@@ -0,0 +1,87 @@
+import 'package:json_annotation/json_annotation.dart';
+import 'package:openfoodfacts/interface/JsonObject.dart';
+import 'package:openfoodfacts/model/LocalizedTag.dart';
+import 'package:openfoodfacts/model/ProductResultFieldAnswer.dart';
+import 'package:openfoodfacts/openfoodfacts.dart';
+
+part 'ProductResultV3.g.dart';
+
+/// API V3 answer from a call to /api/v3/product/$barcode.
+///
+/// Same /api/v3/product/$barcode URL can be used for GET (get that product)
+/// and PATCH (upsert that product and return the modified version).
+@JsonSerializable()
+class ProductResultV3 extends JsonObject {
+  ProductResultV3();
+
+  /// Barcode of a GET operation.
+  @JsonKey(name: 'code', includeIfNull: false)
+  String? barcode;
+
+  /// Result, e.g. "Product found".
+  ///
+  /// Does not seem to be populated for PATH=update.
+  @JsonKey(includeIfNull: false)
+  LocalizedTag? result;
+
+  /// Status.
+  ///
+  /// Typical values: [statusFailure], [statusWarning] or [statusSuccess]
+  @JsonKey(includeIfNull: false)
+  String? status;
+
+  /// Errors.
+  ///
+  /// Typically populated if [status] is [statusFailure].
+  @JsonKey(includeIfNull: false, fromJson: _fromJsonListAnswerForField)
+  List<ProductResultFieldAnswer>? errors;
+
+  /// Warnings.
+  ///
+  /// Typically populated if [status] is [statusWarning].
+  @JsonKey(includeIfNull: false, fromJson: _fromJsonListAnswerForField)
+  List<ProductResultFieldAnswer>? warnings;
+
+  @JsonKey(includeIfNull: false)
+  Product? product;
+
+  /// Possible value for [status]: the operation failed.
+  static const String statusFailure = 'failure';
+
+  /// Possible value for [status]: the operation succeeded with warnings.
+  static const String statusWarning = 'success_with_warnings';
+
+  /// Possible value for [status]: the operation succeeded.
+  static const String statusSuccess = 'success';
+
+  /// Possible value for [result.id]: product found
+  static const String resultProductFound = 'product_found';
+
+  /// Possible value for [result.id]: product not found
+  static const String resultProductNotFound = 'product_not_found';
+
+  factory ProductResultV3.fromJson(Map<String, dynamic> json) =>
+      _$ProductResultV3FromJson(json);
+
+  @override
+  Map<String, dynamic> toJson() => _$ProductResultV3ToJson(this);
+
+  @override
+  String toString() => toJson().toString();
+
+  /// From a `List<AnswerForField>` in `dynamic`'s clothing (JsonKey)
+  static List<ProductResultFieldAnswer>? _fromJsonListAnswerForField(
+      dynamic list) {
+    if (list == null) {
+      return null;
+    }
+    if (list is! List<dynamic>) {
+      throw Exception('Expected type: List<dynamic>, got ${list.runtimeType}');
+    }
+    final List<ProductResultFieldAnswer> result = <ProductResultFieldAnswer>[];
+    for (final item in list) {
+      result.add(ProductResultFieldAnswer.fromJson(item));
+    }
+    return result;
+  }
+}