feat: #233 - new class OpenFoodFactsCountry, clearer than "cc" (#292)

New file:
* `CountryHelper.dart`: country enums and their ISO-2-codes

Impacted files:
* `AbstractQueryConfiguration.dart`: deprecated `String? cc` in favor of `OpenFoodFactsCountry? country`
* `api_getTaxonomy_test.dart`: now using `OpenFoodAPIConfiguration.globalCountry`
* `api_getTaxonomyAdditives_test.dart`: now using `OpenFoodAPIConfiguration.globalCountry`
* `api_getTaxonomyAllergens_test.dart`: now using `OpenFoodAPIConfiguration.globalCountry`
* `api_getTaxonomyCategories_test.dart`: now using `OpenFoodAPIConfiguration.globalCountry`
* `api_getTaxonomyCountries_test.dart`: now using `OpenFoodAPIConfiguration.globalCountry`
* `api_getTaxonomyIngredients_test.dart`: now using `OpenFoodAPIConfiguration.globalCountry`
* `api_getTaxonomyLabels_test.dart`: now using `OpenFoodAPIConfiguration.globalCountry`
* `api_getTaxonomyLanguages_test.dart`: now using `OpenFoodAPIConfiguration.globalCountry`
* `OpenFoodAPIConfiguration.dart`: deprecated `String? globalCC` in favor of `OpenFoodFactsCountry? globalCountry`
* `openfoodfacts.dart`: minor refactoring
* `ProductListQueryConfiguration.dart`: added parameter `OpenFoodFactsCountry? country`
* `ProductQueryConfigurations.dart`: added parameter `OpenFoodFactsCountry? country`
* `ProductSearchQueryConfiguration.dart`: added parameter `OpenFoodFactsCountry? country`
* `TaxonomyAdditive.dart`: added parameter `OpenFoodFactsCountry? country`
* `TaxonomyAllergen.dart`: added parameter `OpenFoodFactsCountry? country`
* `TaxonomyCategory.dart`: added parameter `OpenFoodFactsCountry? country`
* `TaxonomyCountry.dart`: added parameter `OpenFoodFactsCountry? country`
* `TaxonomyIngredient.dart`: added parameter `OpenFoodFactsCountry? country`
* `TaxonomyLabel.dart`: added parameter `OpenFoodFactsCountry? country`
* `TaxonomyLanguage.dart`: added parameter `OpenFoodFactsCountry? country`
* `TaxonomyQueryConfiguration.dart`: deprecated `String? cc` in favor of `OpenFoodFactsCountry? country`

* feat: #233 - explicitly deprecated parameters `lc` and `cc`

Impacted files:
* `api_getProduct_test.dart`: not using deprecated parameter `lc` anymore
* `ProductListQueryConfiguration.dart`: deprecated parameters `lc` and `cc`
* `ProductQueryConfigurations.dart`: deprecated parameters `lc` and `cc`
* `ProductSearchQueryConfiguration.dart`: deprecated parameters `lc` and `cc`
* `TaxonomyAdditive.dart`: deprecated parameter cc`
* `TaxonomyAllergen.dart`: deprecated parameter cc`
* `TaxonomyCategory.dart`: deprecated parameter cc`
* `TaxonomyCountry.dart`: deprecated parameter cc`
* `TaxonomyIngredient.dart`: deprecated parameter cc`
* `TaxonomyLabel.dart`: deprecated parameter cc`
* `TaxonomyLanguage.dart`: deprecated parameter cc`

lib/model/TaxonomyAdditive.dart

@@ -1,6 +1,7 @@
 import 'package:json_annotation/json_annotation.dart';
 import 'package:openfoodfacts/interface/JsonObject.dart';
 import 'package:openfoodfacts/openfoodfacts.dart';
+import 'package:openfoodfacts/utils/CountryHelper.dart';
 import 'package:openfoodfacts/utils/TaxonomyQueryConfiguration.dart';
 import 'package:openfoodfacts/utils/TagType.dart';
 
@@ -335,14 +336,16 @@ class TaxonomyAdditiveQueryConfiguration extends TaxonomyQueryConfiguration<
   TaxonomyAdditiveQueryConfiguration({
     required List<String> tags,
     List<OpenFoodFactsLanguage>? languages = const [],
-    String? cc,
+    @Deprecated('Use parameter country instead') String? cc,
+    OpenFoodFactsCountry? country,
     List<TaxonomyAdditiveField> fields = const [],
     List<Parameter> additionalParameters = const [],
   }) : super(
           TagType.LABELS,
           tags,
           languages: languages,
           cc: cc,
+          country: country,
           includeChildren: false,
           fields: fields,
           additionalParameters: additionalParameters,

lib/model/TaxonomyAllergen.dart

@@ -1,6 +1,7 @@
 import 'package:json_annotation/json_annotation.dart';
 import 'package:openfoodfacts/interface/JsonObject.dart';
 import 'package:openfoodfacts/openfoodfacts.dart';
+import 'package:openfoodfacts/utils/CountryHelper.dart';
 import 'package:openfoodfacts/utils/TaxonomyQueryConfiguration.dart';
 import 'package:openfoodfacts/utils/TagType.dart';
 
@@ -79,14 +80,16 @@ class TaxonomyAllergenQueryConfiguration extends TaxonomyQueryConfiguration<
   TaxonomyAllergenQueryConfiguration({
     required List<String> tags,
     List<OpenFoodFactsLanguage>? languages = const [],
-    String? cc,
+    @Deprecated('Use parameter country instead') String? cc,
+    OpenFoodFactsCountry? country,
     List<TaxonomyAllergenField> fields = const [],
     List<Parameter> additionalParameters = const [],
   }) : super(
           TagType.ALLERGENS,
           tags,
           languages: languages,
           cc: cc,
+          country: country,
           includeChildren: false,
           fields: fields,
           additionalParameters: additionalParameters,

lib/model/TaxonomyCategory.dart

@@ -1,6 +1,7 @@
 import 'package:json_annotation/json_annotation.dart';
 import 'package:openfoodfacts/interface/JsonObject.dart';
 import 'package:openfoodfacts/openfoodfacts.dart';
+import 'package:openfoodfacts/utils/CountryHelper.dart';
 import 'package:openfoodfacts/utils/TaxonomyQueryConfiguration.dart';
 import 'package:openfoodfacts/utils/TagType.dart';
 
@@ -334,7 +335,8 @@ class TaxonomyCategoryQueryConfiguration extends TaxonomyQueryConfiguration<
   TaxonomyCategoryQueryConfiguration({
     required List<String> tags,
     List<OpenFoodFactsLanguage>? languages = const [],
-    String? cc,
+    @Deprecated('Use parameter country instead') String? cc,
+    OpenFoodFactsCountry? country,
     bool includeChildren = false,
     List<TaxonomyCategoryField> fields = const [],
     List<Parameter> additionalParameters = const [],
@@ -343,21 +345,24 @@ class TaxonomyCategoryQueryConfiguration extends TaxonomyQueryConfiguration<
           tags,
           languages: languages,
           cc: cc,
+          country: country,
           includeChildren: includeChildren,
           fields: fields,
           additionalParameters: additionalParameters,
         );
 
   TaxonomyCategoryQueryConfiguration.roots({
     List<OpenFoodFactsLanguage>? languages = const [],
-    String? cc,
+    @Deprecated('Use parameter country instead') String? cc,
+    OpenFoodFactsCountry? country,
     bool includeChildren = false,
     List<TaxonomyCategoryField> fields = const [],
     List<Parameter> additionalParameters = const [],
   }) : super.roots(
           TagType.CATEGORIES,
           languages: languages,
           cc: cc,
+          country: country,
           includeChildren: includeChildren,
           fields: fields,
           additionalParameters: additionalParameters,

lib/model/TaxonomyCountry.dart

@@ -1,6 +1,7 @@
 import 'package:json_annotation/json_annotation.dart';
 import 'package:openfoodfacts/interface/JsonObject.dart';
 import 'package:openfoodfacts/openfoodfacts.dart';
+import 'package:openfoodfacts/utils/CountryHelper.dart';
 import 'package:openfoodfacts/utils/TaxonomyQueryConfiguration.dart';
 import 'package:openfoodfacts/utils/TagType.dart';
 
@@ -103,14 +104,16 @@ class TaxonomyCountryQueryConfiguration
   TaxonomyCountryQueryConfiguration({
     required List<String> tags,
     List<OpenFoodFactsLanguage>? languages = const [],
-    String? cc,
+    @Deprecated('Use parameter country instead') String? cc,
+    OpenFoodFactsCountry? country,
     List<TaxonomyCountryField> fields = const [],
     List<Parameter> additionalParameters = const [],
   }) : super(
           TagType.LABELS,
           tags,
           languages: languages,
           cc: cc,
+          country: country,
           includeChildren: false,
           fields: fields,
           additionalParameters: additionalParameters,

lib/model/TaxonomyIngredient.dart

@@ -1,6 +1,7 @@
 import 'package:json_annotation/json_annotation.dart';
 import 'package:openfoodfacts/interface/JsonObject.dart';
 import 'package:openfoodfacts/openfoodfacts.dart';
+import 'package:openfoodfacts/utils/CountryHelper.dart';
 import 'package:openfoodfacts/utils/TaxonomyQueryConfiguration.dart';
 import 'package:openfoodfacts/utils/TagType.dart';
 
@@ -471,7 +472,8 @@ class TaxonomyIngredientQueryConfiguration extends TaxonomyQueryConfiguration<
   TaxonomyIngredientQueryConfiguration({
     required List<String> tags,
     List<OpenFoodFactsLanguage>? languages = const [],
-    String? cc,
+    @Deprecated('Use parameter country instead') String? cc,
+    OpenFoodFactsCountry? country,
     List<TaxonomyIngredientField> fields = const [],
     List<Parameter> additionalParameters = const [],
     bool includeChildren = false,
@@ -480,21 +482,24 @@ class TaxonomyIngredientQueryConfiguration extends TaxonomyQueryConfiguration<
           tags,
           languages: languages,
           cc: cc,
+          country: country,
           includeChildren: includeChildren,
           fields: fields,
           additionalParameters: additionalParameters,
         );
 
   TaxonomyIngredientQueryConfiguration.roots({
     List<OpenFoodFactsLanguage>? languages = const [],
-    String? cc,
+    @Deprecated('Use parameter country instead') String? cc,
+    OpenFoodFactsCountry? country,
     List<TaxonomyIngredientField> fields = const [],
     List<Parameter> additionalParameters = const [],
     bool includeChildren = false,
   }) : super.roots(
           TagType.INGREDIENTS,
           languages: languages,
           cc: cc,
+          country: country,
           includeChildren: includeChildren,
           fields: fields,
           additionalParameters: additionalParameters,

lib/model/TaxonomyLabel.dart

@@ -1,6 +1,7 @@
 import 'package:json_annotation/json_annotation.dart';
 import 'package:openfoodfacts/interface/JsonObject.dart';
 import 'package:openfoodfacts/openfoodfacts.dart';
+import 'package:openfoodfacts/utils/CountryHelper.dart';
 import 'package:openfoodfacts/utils/TaxonomyQueryConfiguration.dart';
 import 'package:openfoodfacts/utils/TagType.dart';
 
@@ -279,28 +280,32 @@ class TaxonomyLabelQueryConfiguration
   TaxonomyLabelQueryConfiguration({
     required List<String> tags,
     List<OpenFoodFactsLanguage>? languages = const [],
-    String? cc,
+    @Deprecated('Use parameter country instead') String? cc,
+    OpenFoodFactsCountry? country,
     List<TaxonomyLabelField> fields = const [],
     List<Parameter> additionalParameters = const [],
   }) : super(
           TagType.LABELS,
           tags,
           languages: languages,
           cc: cc,
+          country: country,
           includeChildren: false,
           fields: fields,
           additionalParameters: additionalParameters,
         );
 
   TaxonomyLabelQueryConfiguration.roots({
     List<OpenFoodFactsLanguage>? languages = const [],
-    String? cc,
+    @Deprecated('Use parameter country instead') String? cc,
+    OpenFoodFactsCountry? country,
     List<TaxonomyLabelField> fields = const [],
     List<Parameter> additionalParameters = const [],
   }) : super.roots(
           TagType.LABELS,
           languages: languages,
           cc: cc,
+          country: country,
           includeChildren: false,
           fields: fields,
           additionalParameters: additionalParameters,

lib/model/TaxonomyLanguage.dart

@@ -1,6 +1,7 @@
 import 'package:json_annotation/json_annotation.dart';
 import 'package:openfoodfacts/interface/JsonObject.dart';
 import 'package:openfoodfacts/openfoodfacts.dart';
+import 'package:openfoodfacts/utils/CountryHelper.dart';
 import 'package:openfoodfacts/utils/TaxonomyQueryConfiguration.dart';
 import 'package:openfoodfacts/utils/TagType.dart';
 
@@ -94,14 +95,16 @@ class TaxonomyLanguageQueryConfiguration extends TaxonomyQueryConfiguration<
   TaxonomyLanguageQueryConfiguration({
     required List<String> tags,
     List<OpenFoodFactsLanguage>? languages = const [],
-    String? cc,
+    @Deprecated('Use parameter country instead') String? cc,
+    OpenFoodFactsCountry? country,
     List<TaxonomyLanguageField> fields = const [],
     List<Parameter> additionalParameters = const [],
   }) : super(
           TagType.LABELS,
           tags,
           languages: languages,
           cc: cc,
+          country: country,
           includeChildren: false,
           fields: fields,
           additionalParameters: additionalParameters,

lib/openfoodfacts.dart

@@ -835,7 +835,7 @@ class OpenFoodAPIClient {
       queryParameters: <String, String>{
         'fields': KNOWLEDGE_PANELS_FIELD,
         'lc': configuration.language!.code,
-        'cc': configuration.cc!,
+        'cc': configuration.computeCountryCode()!,
       },
     );
 

lib/utils/AbstractQueryConfiguration.dart

@@ -1,5 +1,6 @@
 import 'package:openfoodfacts/interface/Parameter.dart';
 import 'package:openfoodfacts/model/parameter/TagFilter.dart';
+import 'package:openfoodfacts/utils/CountryHelper.dart';
 import 'package:openfoodfacts/utils/LanguageHelper.dart';
 import 'package:openfoodfacts/utils/OpenFoodAPIConfiguration.dart';
 import 'package:openfoodfacts/utils/ProductFields.dart';
@@ -29,7 +30,13 @@ abstract class AbstractQueryConfiguration {
   @Deprecated('Use parameters language or languages instead')
   String? lc;
 
+  // TODO: deprecated from 2021-11-15 (#233); remove when old enough
+  @Deprecated('Use parameter country instead')
   String? cc;
+
+  /// The country for this query, if any.
+  final OpenFoodFactsCountry? country;
+
   List<ProductField>? fields;
 
   List<Parameter> additionalParameters;
@@ -39,6 +46,7 @@ abstract class AbstractQueryConfiguration {
     this.languages,
     this.lc,
     this.cc,
+    this.country,
     this.fields,
     this.additionalParameters = const [],
   }) {
@@ -78,10 +86,9 @@ abstract class AbstractQueryConfiguration {
       result.putIfAbsent('lc', () => lc!);
     }
 
-    if (cc != null) {
-      result.putIfAbsent('cc', () => cc!);
-    } else if (OpenFoodAPIConfiguration.globalCC != null) {
-      result.putIfAbsent('cc', () => OpenFoodAPIConfiguration.globalCC!);
+    final String? countryCode = computeCountryCode();
+    if (countryCode != null) {
+      result.putIfAbsent('cc', () => countryCode);
     }
 
     if (fields != null) {
@@ -110,4 +117,8 @@ abstract class AbstractQueryConfiguration {
 
     return result;
   }
+
+  String? computeCountryCode() =>
+      // ignore: deprecated_member_use_from_same_package
+      OpenFoodAPIConfiguration.computeCountryCode(country, cc);
 }