Merge pull request #320 from Shopify/add-zip_requirement-and-tax_incl…

…usive-methods-to-country-regions

Add zip requirement and tax inclusive methods to country regions

CHANGELOG.md

@@ -26,8 +26,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - Security in case of vulnerabilities.
 
 ## [Unreleased]
+- Add zip requirement and tax inclusive methods to country regions [#320](https://github.com/Shopify/worldwide/pull/320)
 
-Nil.
 ---
 
 ## [1.14.4] - 2024-12-12

lib/worldwide/region.rb

@@ -163,6 +163,9 @@ class Region
     # Note that this should really be translated; showing this untranslated name to users is a bad idea.
     attr_reader :tax_name
 
+    # Whether the region uses tax-inclusive pricing.
+    attr_accessor :tax_inclusive
+
     # "generic" VAT tax rate on "most" goods
     attr_reader :tax_rate
 
@@ -198,7 +201,7 @@ class Region
     attr_accessor :zip_example
 
     # Is a zip value required in this region?  (Possible values:  "optional", "recommended", "required")
-    attr_accessor :zip_requirement
+    attr_writer :zip_requirement
 
     # A list of character sequences with which a postal code in this region may start.
     attr_accessor :zip_prefixes
@@ -276,6 +279,7 @@ def initialize(
       @partial_zip_regex = nil
       @phone_number_prefix = nil
       @tags = []
+      @tax_inclusive = false
       @timezone = nil
       @timezones = {}
       @unit_system = nil
@@ -435,13 +439,23 @@ def zip_autofill
 
     # is a postal code required for this region?
     def zip_required?
-      if zip_requirement.nil?
+      if @zip_requirement.nil?
         !zip_regex.nil?
       else
-        REQUIRED == zip_requirement
+        REQUIRED == @zip_requirement
       end
     end
 
+    # Returns whether (and how firmly) we require a value in the zip field
+    # Possible returns:
+    #  - "required" means a value must be supplied
+    #  - "recommended" means a value is optional, but we recommend providing one
+    #  - "optional" means a value is optional, and we say it is optional
+    # @return [String]
+    def zip_requirement
+      @zip_requirement || (zip_required? ? REQUIRED : OPTIONAL)
+    end
+
     # is a neighborhood required for this region?
     def neighborhood_required?
       additional_field_required?("neighborhood")

lib/worldwide/regions_loader.rb

@@ -114,6 +114,7 @@ def apply_territory_attributes(region, spec)
       region.partial_zip_regex = spec["partial_zip_regex"]
       region.phone_number_prefix = spec["phone_number_prefix"]
       region.tags = spec["tags"] || []
+      region.tax_inclusive = spec["tax_inclusive"] || false
       region.timezone = spec["timezone"]
       region.timezones = spec["timezones"] || {}
       region.week_start_day = spec["week_start_day"] || "sunday"

test/worldwide/region_test.rb

@@ -346,6 +346,14 @@ class RegionTest < ActiveSupport::TestCase
       end
     end
 
+    test "#zip_requirement returns zip requirement" do
+      assert_equal "required", Worldwide.region(code: "CN").zip_requirement # set as required
+      assert_equal "recommended", Worldwide.region(code: "AM").zip_requirement # set as recommended
+      assert_equal "optional", Worldwide.region(code: "AF").zip_requirement # set as optional
+      assert_equal "required", Worldwide.region(code: "AC").zip_requirement # not set but has potal code regex
+      assert_equal "optional", Worldwide.region(code: "TZ").zip_requirement # not set
+    end
+
     test "#neighborhood_required? returns values as expected" do
       neighborhood_not_required_countries = [:ca, :cl, :mx, :id]
       neighborhood_required_countries = [:ph, :vn, :tr]
@@ -501,6 +509,11 @@ class RegionTest < ActiveSupport::TestCase
       end
     end
 
+    test "#tax_inclusive returns the configured value or false" do
+      assert Worldwide.region(code: "AD").tax_inclusive
+      refute Worldwide.region(code: "CA").tax_inclusive
+    end
+
     test "#example_city returns values as expected" do
       assert_equal "Los Angeles", Worldwide.region(code: "US").zone(code: "CA").example_city
     end

test/worldwide/region_yml_consistency_test.rb

@@ -70,6 +70,38 @@ class RegionYmlConsistencyTest < ActiveSupport::TestCase
       end
     end
 
+    test "country currencies are all 3-character strings and exist" do
+      expected_format = /\A[A-Z]{3}\z/
+
+      Regions.all.select(&:country?).each do |country|
+        currency = country.currency
+
+        assert_predicate currency, :present?, "#{country.iso_code} currency is empty"
+        assert_kind_of Currency, currency, "#{country.iso_code} currency was not a Currency"
+        assert_match expected_format, currency.currency_code, "#{country.iso_code} currency.curency_code was not a 3-character capitalized alphabetical code"
+      end
+    end
+
+    test "country phone_number_prefix attributes are all numeric and exist" do
+      expected_format = /\A0|[1-9][0-9]{0,2}\z/
+
+      Regions.all.select(&:country?).each do |country|
+        phone_number_prefix = country.phone_number_prefix
+
+        assert_predicate phone_number_prefix, :present?, "#{country.iso_code} phone_number_prefix is empty"
+        assert_match expected_format, phone_number_prefix.to_s, "#{country.iso_code} phone_number_prefix was not a 1-3 digit code"
+      end
+    end
+
+    test "country group attribute is always present and is a string" do
+      Regions.all.select(&:country?).each do |country|
+        group = country.group
+
+        assert_predicate group, :present?, "#{country.iso_code} group is empty"
+        assert_kind_of String, group, "#{country.iso_code} group was not a String"
+      end
+    end
+
     test "format keys must belong to a limited set of required and allowed keys" do
       allowed_keys = ["edit", "show"]
       required_format_keys = ["{firstName}", "{lastName}", "{company}", "{address1}", "{address2}", "{country}", "{phone}"]
@@ -343,6 +375,16 @@ class RegionYmlConsistencyTest < ActiveSupport::TestCase
       end
     end
 
+    test "unit_system is a valid value" do
+      Regions.all.select(&:country?).each do |country|
+        unit_system = country.unit_system
+
+        valid_values = ["metric", "imperial"]
+
+        assert_includes valid_values, unit_system
+      end
+    end
+
     test "all countries and provinces have tax information" do
       Regions.all.select do |region|
         region.country? || region.province?