costa_rica_address_utils 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5499eeebb373e3b50ca5eb2c4e566830f157e390a39893a3f55f613b968a7466
-  data.tar.gz: 5b7ae3823faf5a3792398aeca1d7226db12d9659c95245ca2b97f8299ee722c2
+  metadata.gz: e88494ff983e9e75ca80537f1d42f97bd31a0ce606f17a450bc7a4a6ec6dd7db
+  data.tar.gz: 914e71a23e8a05acbf39aa99a8d85c87decd700403e420fcc02324f448409308
 SHA512:
-  metadata.gz: e237a271be1b395114a457b55ec458e4a8bead6d01f256ea7bcc5abaa47de0839a7fa8728abf56cb738e6922951da0d69b5b01b9fc5efc4c801cdd085dbf50e1
-  data.tar.gz: 208affcee44657c5f423d9c13e4fa49111a34580bf5d72c0ce3829574198345d44ddd1968a7536b07cef462a79d3386ec100fa31a7c6b6a1d52a7d4619a47e9b
+  metadata.gz: 35c91696f8bf675e556daf9b1393bcade9d4fa3ebe03fdab5bfbebbf9402cf128966078ab23e4256d5d672160c4ba40f0fb27ee52b9b9c9053be2e51e75eda34
+  data.tar.gz: 1a943483975c277de9b5287e356a9bbf50c7fbcc4666444108725f77bb4943842fad28b661c85906af838f2a0fce9b03bc015bff7b0f0797b00c0cc0bd01b064

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 ## [Unreleased]
 
+## [0.4.0]
+
+* Move existing logic for main module to its own module called `CostaRica`
+* Create new module `Guatemala` for Guatemala address logic
+* New method `for_country` to explicitly use methods for each country
+* Extract method `build_address_from_provider` as a global method instead of per region to build an address from an external provider (Shopify, Brightpearl, etc)
+
+> To avoid breaking calls of older versions, if the methods are called directly with `CostaRicaAddressUtils` it will automatically use the methods from `CostaRica` module.
+
 ## [0.3.2]
 
 * Add missing accents from GT dataset on top level items

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    costa_rica_address_utils (0.3.2)
+    costa_rica_address_utils (0.4.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -40,11 +40,17 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 To install this gem onto your local machine, run `bundle exec rake install`. 
 
-To release a new version, update the version number in `version.rb` and `Gemfile.lock` (using bundle), and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+## Release
 
-> `Gemfile.lock` update for version is done after running `bundle install` with the `version.rb` updated
+To release a new version follow these steps:,
+1. Update CHANGELOG.md with the new version changes
+2. Update the version number in `version.rb` 
+3. Execute bundle to update version on `Gemfile.lock` automatically
+4. Commit the changes and change the branch to `main`
+5. Run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 > Remember to execute `bundle exec rake release` on `main` branch
+> `Gemfile.lock` update for version is done after running `bundle install` with the `version.rb` updated
 
 ## Contributing
 

data/lib/costa_rica_address_utils/costa_rica.rb

@@ -0,0 +1,81 @@
+require 'json'
+
+# TODO: find way to optimize dataset loading
+
+module CostaRicaAddressUtils
+  module CostaRica
+    JSON_FILE_PATH = File.join(File.dirname(__FILE__), '..', '..', 'data', 'locations_dataset.json')
+
+    # Load the JSON file and parse it into a Ruby object for general usage
+    LOCATIONS_DATASET = JSON.parse(File.read(JSON_FILE_PATH))
+
+    class Error < StandardError; end
+    # Your code goes here...
+
+    # Fetch the address data from provided input, return options for subaddresses on each level and zip code if full address is valid
+    def fetch_address_data(province:, canton: nil, district: nil)
+      raise CostaRicaAddressUtils::InvalidData, 'Province is required' if province.nil? || province.empty?
+
+      province_data = LOCATIONS_DATASET[province]
+      canton_data = !!province_data ? province_data['cantons'][canton] : nil
+      district_data = !!canton_data ? canton_data['districts'][district] : nil
+
+      canton_options = !!province_data ? province_data['cantons'].keys : [] # Cantons options, only if province is valid
+      district_options = !!canton_data ? canton_data['districts'].keys : [] # Districts options, only if canton is valid
+      zip = (!!district_data && district_data['zip_code']) || nil # Zip code, only if full address is valid
+
+      {
+        zip: zip,
+        # Names options
+        province_options: LOCATIONS_DATASET.keys,
+        canton_options: canton_options,
+        district_options: district_options
+      }
+    end
+
+    # Get one address information from a zip code
+    def fetch_address_from_zip(zip_code)
+      return nil unless zip_valid?(zip_code)
+
+      zip_code_s = zip_code.to_s
+      LOCATIONS_DATASET.each do |province, province_data|
+        province_data['cantons'].each do |canton, canton_data|
+          canton_data['districts'].each do |district, district_data|
+            if district_data['zip_code'] == zip_code_s
+              return {
+                province: province,
+                canton: canton,
+                district: district,
+                zip: zip_code_s
+              }
+            end
+          end
+        end
+      end
+
+      nil
+    end
+
+    def fetch_address_from_zip!(zip_code)
+      raise "Zip code provided #{zip_code} is invalid. Must be a 5 digits number" unless zip_valid?(zip_code)
+
+      fetch_address_from_zip(zip_code)
+    end
+
+    def address_valid?(province:, canton:, district:)
+      is_valid = true
+      begin
+        data = fetch_address_data(province: province, canton: canton, district: district)
+        is_valid = !!data[:zip] # Is valid if matched to a zip code
+      rescue CostaRicaAddressUtils::InvalidData => e
+        is_valid = false
+      end
+
+      is_valid
+    end
+
+    def zip_valid?(zip_code)
+      !!zip_code && zip_code.to_s.length == 5
+    end
+  end # CostaRica
+end

data/lib/costa_rica_address_utils/guatemala.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module CostaRicaAddressUtils
+  module Guatemala
+    # Guatemala-specific implementation
+    JSON_FILE_PATH = File.join(File.dirname(__FILE__), '..', '..', 'data', 'guatemala_dataset.json')
+    LOCATIONS_DATASET = JSON.parse(File.read(JSON_FILE_PATH))
+
+    # Your Guatemala-specific methods here
+
+    # For a given address of 2 levels, return options for each level found and zip code if full address is valid
+    def self.fetch_address_data(department:, municipality:)
+      raise CostaRicaAddressUtils::InvalidData, 'Department is required' if department.nil? || department.empty?
+
+      department_data = LOCATIONS_DATASET[department]
+      municipality_data = !!department_data ? department_data['locationsLevel2'][municipality] : nil
+
+      # Municipality options(lv2), only if department(lv1) is valid
+      municipality_options = !!department_data ? department_data['locationsLevel2'].keys : []
+      zip = (!!municipality_data && municipality_data['zipCode']) || nil # Zip code, only if full address is valid
+
+      {
+        zip: zip,
+        # Names options
+        department_options: LOCATIONS_DATASET.keys,
+        municipality_options: municipality_options
+      }
+    end
+
+    # Get one address information from a zip code
+    def self.fetch_address_from_zip(zip_code)
+      return nil unless zip_valid?(zip_code)
+
+      zip_code_s = zip_code.to_s
+      LOCATIONS_DATASET.each do |department, department_data|
+        department_data['locationsLevel2'].each do |municipality, municipality_data|
+          if municipality_data['zipCode'] == zip_code_s
+            return {
+              department: department,
+              municipality: municipality,
+              zip: zip_code_s
+            }
+          end
+        end
+      end
+
+      nil
+    end
+
+    def self.address_valid?(department:, municipality:)
+      is_valid = true
+      begin
+        data = fetch_address_data(department: department, municipality: municipality)
+        is_valid = !!data[:zip] # Is valid if matched to a zip code
+      rescue CostaRicaAddressUtils::InvalidData => e
+        is_valid = false
+      end
+
+      is_valid
+    end
+  end # Guatemala
+end # CostaRicaAddressUtils

data/lib/costa_rica_address_utils/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CostaRicaAddressUtils
-  VERSION = '0.3.2'
+  VERSION = '0.4.0'
 end

data/lib/costa_rica_address_utils.rb

@@ -1,118 +1,67 @@
 # frozen_string_literal: true
-# TODO find way to optimize dataset loading
-require 'json'
-require_relative "costa_rica_address_utils/version"
-require_relative "costa_rica_address_utils/errors"
 
-JSON_FILE_PATH = File.join(File.dirname(__FILE__), '..', 'data', 'locations_dataset.json')
+require_relative 'costa_rica_address_utils/version'
+require_relative 'costa_rica_address_utils/errors'
+require_relative 'costa_rica_address_utils/costa_rica'
+require_relative 'costa_rica_address_utils/guatemala'
 
-module CostaRicaAddressUtils
-  # Load the JSON file and parse it into a Ruby object for general usage
-  LOCATIONS_DATASET = JSON.parse(File.read(JSON_FILE_PATH))
-  VAlID_PROVIDERS = [:shopify, :brightpearl]
+module CostaRicaAddressUtils # rubocop:disable Style/Documentation
+  # Backwards compatibility before usage of for_country
+  # Old version will be able to call methods with CostaRicaAddressUtils directly
+  extend CostaRicaAddressUtils::CostaRica
 
-  class Error < StandardError; end
-  # Your code goes here...
+  SUPPORTED_COUNTRIES = %i[costa_rica guatemala].freeze
+  VALID_INPUT_PROVIDERS = %i[shopify brightpearl].freeze
 
-  # Fetch the address data from provided input, return options for subaddresses on each level and zip code if full address is valid
-  def self.fetch_address_data(province:, canton: nil, district: nil)
-    raise InvalidData, "Province is required" if province.nil? || province.empty?
+  # TODO: merge the methods from both countries using new dataset for costa rica instead of previous one
+  # Newer files contains a standarized format for fields.
 
-    province_data = LOCATIONS_DATASET[province]
-    canton_data = !!province_data ? province_data["cantons"][canton] : nil
-    district_data = !!canton_data ? canton_data["districts"][district] : nil
-
-    canton_options = !!province_data ? province_data["cantons"].keys : [] # Cantons options, only if province is valid
-    district_options = !!canton_data ? canton_data["districts"].keys : [] # Districts options, only if canton is valid
-    zip = (!!district_data && district_data["zip_code"]) || nil # Zip code, only if full address is valid
-
-    return {
-      zip: zip,
-      # Names options
-      province_options: LOCATIONS_DATASET.keys,
-      canton_options: canton_options,
-      district_options: district_options,
-    }
-  end
-
-  # Get one address information from a zip code
-  def self.fetch_address_from_zip(zip_code)
-    return nil unless zip_valid?(zip_code)
-    zip_code_s = zip_code.to_s
-    LOCATIONS_DATASET.each do |province, province_data|
-      province_data["cantons"].each do |canton, canton_data|
-        canton_data["districts"].each do |district, district_data|
-          if district_data["zip_code"] == zip_code_s
-            return {
-              province: province,
-              canton: canton,
-              district: district,
-              zip: zip_code_s,
-            }
-          end
-        end
-      end
-    end
-
-    return nil
-  end
-
-  def self.fetch_address_from_zip!(zip_code)
-    raise "Zip code provided #{zip_code} is invalid. Must be a 5 digits number" unless zip_valid?(zip_code)
-    fetch_address_from_zip(zip_code)
-  end
-
-  def self.address_valid?(province:, canton:, district:)
-    is_valid = true
-    begin
-      data = fetch_address_data(province: province, canton: canton, district: district)
-      is_valid = !!data[:zip] # Is valid if matched to a zip code
-    rescue InvalidData => e
-      is_valid = false
+  def self.for_country(country)
+    case country.to_sym
+    when :costa_rica
+      CostaRicaAddressUtils::CostaRica
+    when :guatemala
+      CostaRicaAddressUtils::Guatemala
+    else
+      raise ArgumentError, "Unsupported country: #{country}. Supported countries are: #{SUPPORTED_COUNTRIES}"
     end
-
-    return is_valid
-  end
-
-  def self.zip_valid?(zip_code)
-    !!zip_code && zip_code.to_s.length == 5
   end
 
   # Build a Costa Rica address from an address of an external provider (Shopify, Brightpearl, etc)
   # https://shopify.dev/api/admin-graphql/2022-10/objects/mailingaddress
   # https://api-docs.brightpearl.com/contact/postal-address/get.html
-  def self.build_address_from_provider(address:, provider:) 
+  # Standarized format locationLevelX for the address Province/Department, Municipality/Canton, District/Parish
+  # since they are named differently in each country
+  def self.build_address_from_provider(address:, provider:)
     case provider
     when :shopify
-      return {
+      {
         name: address.name, # Customer name
         address1: address.address1,
-        
-        province: address.province,
-        canton: address.city,
-        district: address.address2,
+
+        locationLevel1: address.province,
+        locationLevel2: address.city,
+        locationLevel3: address.address2,
         zip: address.zip,
 
         national_id: address.company,
-        phone: address.phone,
+        phone: address.phone
       }
     when :brightpearl
-      return {
-        name: address["addressFullName"], # Customer name
-        address1: address["addressLine1"],
-        
-        province: address["addressLine4"],
-        canton: address["addressLine3"],
-        district: address["addressLine2"],
-        zip: address["postalCode"],
+      {
+        name: address['addressFullName'], # Customer name
+        address1: address['addressLine1'],
 
-        national_id: address["companyName"],
-        phone: address["telephone"],
+        locationLevel1: address['addressLine4'],
+        locationLevel2: address['addressLine3'],
+        locationLevel3: address['addressLine2'],
+        zip: address['postalCode'],
+
+        national_id: address['companyName'],
+        phone: address['telephone']
       }
     else
-      raise InvalidData("Invalid provider, valid providers are: #{VAlID_PROVIDERS}")
+      raise InvalidData("Invalid provider, valid providers are: #{VALID_INPUT_PROVIDERS}")
     end
   end
-
-  private
-end # module CostaRicaAddressUtils
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: costa_rica_address_utils
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
 platform: ruby
 authors:
 - vicvans20
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-11-21 00:00:00.000000000 Z
+date: 2025-01-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: byebug
@@ -45,7 +45,9 @@ files:
 - data/guatemala_dataset.json
 - data/locations_dataset.json
 - lib/costa_rica_address_utils.rb
+- lib/costa_rica_address_utils/costa_rica.rb
 - lib/costa_rica_address_utils/errors.rb
+- lib/costa_rica_address_utils/guatemala.rb
 - lib/costa_rica_address_utils/version.rb
 - sig/costa_rica_address_utils.rbs
 homepage: https://github.com/vicvans20/costa_rica_address_utils