mainstreet 0.1.0 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: d572831c5d0c80c6580ac885edf6c1ea8137589d
-  data.tar.gz: 3f50e8e84d9edad8918aa83e9b87ca6f450bc196
+SHA256:
+  metadata.gz: '08e1a7061a00946e499902c0eab2b4a9ab51971a69ab722626b89047aa4c1eca'
+  data.tar.gz: e7696455f9372bdb90b889fb8193a499f992a6ecc3b1a6c51fc2c1cf732ca0ce
 SHA512:
-  metadata.gz: f9b58c621595ee590c924beb58aa5f4c6402c9df339fc62fd78ea3789ca8ec23accc756f5dabc41a5733c42d98271431db6e1eba007d21ed8dbf2c232fe69134
-  data.tar.gz: 954950d8881fd942e1f159e540eb1634780bb36350720402df09f6f25326490d35e1f38d85f9dd98aa4e2ec0fcf0fccc1d34b5a7024d9dc1d9438ada00558e15
+  metadata.gz: e9a5c7b6147226624d4492df51bde93d1ae3c35f3da48a3f2e5730f8e649011e1108e13bdf2469e32feae23e722140721907a029d9343c3d8d52f9aef653cc3f
+  data.tar.gz: 52038f683d0fa478446c4a04d1a74aa545bac6f75b54d9bc98a5827855374ca88383e9deb32ae3479269e742765bb06b75dca6249f7dad786ce601cb69f480ed

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+## 0.2.3 (2022-02-08)
+
+- Added `lookup` option
+- Fixed duplicate API calls for invalid addresses
+
+## 0.2.2 (2020-04-16)
+
+- Fixed bug with SmartyStreets and ZIP code only addresses
+
+## 0.2.1 (2019-10-04)
+
+- Added support for i18n
+- Added support for more validation options like `if` and `on`
+- Specified minimum Geocoder version
+
+## 0.2.0 (2018-11-30)
+
+- Added `AddressVerifier`
+- Added `validates_address` method
+- Removed `acts_as_address` method
+
+## 0.1.0 (2017-05-01)
+
+- Added more validation
+- Fixed model generator for Rails 5
+
+## 0.0.1 (2015-03-14)
+
+- First release

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015 Andrew Kane
+Copyright (c) 2015-2022 Andrew Kane
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,95 +1,163 @@
 # MainStreet
 
-A standard US address model for Rails
+Address verification for Ruby and Rails
 
-You get:
+:earth_americas: Supports international addresses
 
-- verification
-- standardization
-- geocoding
+[![Build Status](https://github.com/ankane/mainstreet/workflows/build/badge.svg?branch=master)](https://github.com/ankane/mainstreet/actions)
+
+## Installation
+
+Add this line to your application’s Gemfile:
+
+```ruby
+gem "mainstreet"
+```
 
 ## How It Works
 
+MainStreet uses [Geocoder](https://github.com/alexreisner/geocoder) for address verification, which has a number of [3rd party services](https://github.com/alexreisner/geocoder/blob/master/README_API_GUIDE.md#global-street-address-lookups) you can use. If you adhere to GDPR, be sure to add the service to your subprocessor list.
+
+With some services, bad street numbers, units, and postal codes may pass verification. For full verification, get an account with [SmartyStreets](https://smartystreets.com). The free plan supports 250 lookups per month for US addresses, and plans for international addresses start at $7. To use it, set:
+
 ```ruby
-Address.create!(street: "1 infinite loop", zip_code: "95014")
+ENV["SMARTY_STREETS_AUTH_ID"] = "auth-id"
+ENV["SMARTY_STREETS_AUTH_TOKEN"] = "auth-token"
 ```
 
-This creates an address with:
+## How to Use
 
-- street - `1 Infinite Loop`
-- city - `Cupertino`
-- state - `CA`
-- zip_code - `95014`
-- latitude - `37.33053`
-- longitude - `-122.02887`
-- original_attributes - `{"street"=>"1 infinite loop", "street2"=>nil, "city"=>nil, "state"=>nil, "zip_code"=>"95014"}`
-- verification_info
+Check an address with:
 
-### Verification
+```ruby
+address = "1600 Pennsylvania Ave NW, Washington DC 20500"
+verifier = MainStreet::AddressVerifier.new(address)
+verifier.success?
+```
 
-By default, MainStreet performs ZIP code verification.
+If verification fails, get the failure message with:
 
 ```ruby
-address = Address.new(street:"1 infinite loop", zip_code: "95015")
-address.valid?
-# false
-address.errors.full_messages
-# ["Did you mean 95014?"]
+verifier.failure_message
 ```
 
-For full verification, including unit number, [see below](#full-verification).
+Get details about the result with:
 
-## Installation
+```ruby
+verifier.result
+```
 
-Add this line to your application’s Gemfile:
+Get the latitude and longitude with:
 
 ```ruby
-gem 'mainstreet'
+verifier.latitude
+verifier.longitude
 ```
 
-To create a new address model, run:
+## Active Record
 
-```sh
-rails g mainstreet:address
+For Active Record models, use:
+
+```ruby
+class User < ApplicationRecord
+  validates_address fields: [:street, :street2, :city, :state, :postal_code]
+end
 ```
 
-This creates an `Address` model with:
+The order should be the same as if you were to write the address out.
+
+For performance, the address is only verified if at least one of the fields changes. Set your own condition with:
 
-- street
-- street2
-- city
-- state
-- zip_code
-- latitude
-- longitude
-- original_attributes
-- verification_info
+```ruby
+class User < ApplicationRecord
+  validates_address if: -> { something_changed? }, ...
+end
+```
 
-To add to an existing model:
+Geocode the address with:
 
-1. Use `alias_attribute` to map existing field names
-2. Add new fields like `original_attributes` and `verification_info`
-3. Add `acts_as_address` to your model
+```ruby
+class User < ApplicationRecord
+  validates_address geocode: true, ...
+end
+```
 
-## Full Verification
+The `latitude` and `longitude` fields are used by default. Specify the fields with:
 
-[SmartyStreets](https://smartystreets.com/features) is required for full verification. The free plan supports 250 lookups per month.
+```ruby
+class User < ApplicationRecord
+  validates_address geocode: {latitude: :lat, longitude: :lon}, ...
+end
+```
 
-Set:
+Empty addresses are not verified. To require an address, add your own validation.
 
 ```ruby
-ENV["SMARTY_STREETS_AUTH_ID"] = "auth-id"
-ENV["SMARTY_STREETS_AUTH_TOKEN"] = "auth-token"
+class User < ApplicationRecord
+  validates :street, presence: true
+end
 ```
 
-To test it, run:
+## SmartyStreets
+
+With SmartyStreets, you must pass the country for non-US addresses.
+
+```ruby
+MainStreet::AddressVerifier.new(address, country: "France")
+```
+
+Here’s the list of [supported countries](https://smartystreets.com/docs/cloud/international-street-api#countries). You can pass the name, ISO-3, ISO-2, or ISO-N code (like `France`, `FRA`, `FR`, or `250`).
+
+For Active Record, use:
+
+```ruby
+class User < ApplicationRecord
+  validates_address country: "France", ...
+end
+```
+
+Or use a proc to make it dynamic
+
+```ruby
+class User < ApplicationRecord
+  validates_address country: -> { country }, ...
+end
+```
+
+## Internationalization (i18n)
+
+You can customize error messages with the [i18n](https://github.com/ruby-i18n/i18n) gem. In Rails, add to the appropriate `config/locales` file:
+
+```yml
+en:
+  mainstreet:
+    errors:
+      messages:
+        unconfirmed: Address can't be confirmed
+        apt_unconfirmed: Apartment or suite can't be confirmed
+        apt_missing: Apartment or suite is missing
+```
+
+## Data Protection
+
+We recommend encrypting street information and postal code (at the very least) for user addresses. [Lockbox](https://github.com/ankane/lockbox) is great for this. Check out [this article](https://ankane.org/sensitive-data-rails) for more details.
 
 ```ruby
-address = Address.new(street: "122 Mast Rd", zip_code: "03861")
-address.valid?
-# should get false
+class User < ApplicationRecord
+  encrypts :street, :postal_code
+end
 ```
 
+## Upgrading
+
+### 0.2.0
+
+See the [upgrade guide](docs/0-2-Upgrade.md)
+
+## History
+
+View the [changelog](https://github.com/ankane/mainstreet/blob/master/CHANGELOG.md)
+
 ## Contributing
 
 Everyone is encouraged to help improve this project. Here are a few ways you can help:
@@ -98,3 +166,12 @@ Everyone is encouraged to help improve this project. Here are a few ways you can
 - Fix bugs and [submit pull requests](https://github.com/ankane/mainstreet/pulls)
 - Write, clarify, or fix documentation
 - Suggest or add new features
+
+To get started with development:
+
+```sh
+git clone https://github.com/ankane/mainstreet.git
+cd mainstreet
+bundle install
+bundle exec rake test
+```

data/lib/mainstreet/address_verifier.rb

@@ -0,0 +1,82 @@
+module MainStreet
+  class AddressVerifier
+    def initialize(address, country: nil, locale: nil)
+      @address = address
+      @country = country
+      @locale = locale
+    end
+
+    def success?
+      failure_message.nil?
+    end
+
+    def failure_message
+      if !result
+        message :unconfirmed, "Address can't be confirmed"
+      elsif result.respond_to?(:analysis)
+        analysis = result.analysis
+
+        if analysis["verification_status"]
+          case analysis["verification_status"]
+          when "Verified"
+            nil # success!!
+          when "Ambiguous", "Partial", "None"
+            message :unconfirmed, "Address can't be confirmed"
+          else
+            raise "Unknown verification_status"
+          end
+        elsif analysis["dpv_match_code"]
+          case analysis["dpv_match_code"]
+          when "Y"
+            nil # success!!
+          when "N"
+            message :unconfirmed, "Address can't be confirmed"
+          when "S"
+            message :apt_unconfirmed, "Apartment or suite can't be confirmed"
+          when "D"
+            message :apt_missing, "Apartment or suite is missing"
+          else
+            raise "Unknown dpv_match_code"
+          end
+        end
+      end
+    end
+
+    def result
+      return @result if defined?(@result)
+
+      @result = begin
+        options = {lookup: MainStreet.lookup}
+        options[:country] = @country if @country && !usa?
+        # don't use smarty streets zipcode only API
+        # keep mirrored with geocoder gem, including \Z
+        # \Z is the same as \z when strip is used
+        if @address.to_s.strip !~ /\A\d{5}(-\d{4})?\Z/
+          Geocoder.search(@address, options).first
+        end
+      end
+    end
+
+    def latitude
+      result && result.latitude
+    end
+
+    def longitude
+      result && result.longitude
+    end
+
+    private
+
+    def usa?
+      ["United States", "USA", "US", "840"].include?(@country.to_s)
+    end
+
+    def message(key, default)
+      if defined?(I18n)
+        I18n.t(key, scope: [:mainstreet, :errors, :messages], locale: @locale, default: default)
+      else
+        default
+      end
+    end
+  end
+end

data/lib/mainstreet/model.rb

@@ -0,0 +1,35 @@
+module MainStreet
+  module Model
+    def validates_address(fields:, geocode: false, country: nil, **options)
+      fields = Array(fields.map(&:to_s))
+      geocode_options = {latitude: :latitude, longitude: :longitude}
+      geocode_options = geocode_options.merge(geocode) if geocode.is_a?(Hash)
+      options[:if] ||= -> { fields.any? { |f| changes.key?(f.to_s) } } unless options[:unless]
+
+      class_eval do
+        validate :verify_address, **options
+
+        define_method :verify_address do
+          address = fields.map { |v| send(v).presence }.compact.join(", ")
+
+          if address.present?
+            # must use a different variable than country
+            record_country = instance_exec(&country) if country.respond_to?(:call)
+            verifier = MainStreet::AddressVerifier.new(address, country: record_country)
+            if verifier.success?
+              if geocode
+                self.send("#{geocode_options[:latitude]}=", verifier.latitude)
+                self.send("#{geocode_options[:longitude]}=", verifier.longitude)
+              end
+            else
+              errors.add(:base, verifier.failure_message)
+            end
+
+            # legacy - for standardize_address method
+            @address_verification_result = verifier.result
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mainstreet/version.rb

@@ -1,3 +1,3 @@
-module Mainstreet
-  VERSION = "0.1.0"
+module MainStreet
+  VERSION = "0.2.3"
 end

data/lib/mainstreet.rb

@@ -1,95 +1,32 @@
-require "mainstreet/version"
+# dependencies
 require "geocoder"
 
-module Mainstreet
+# modules
+require "mainstreet/address_verifier"
+require "mainstreet/version"
+
+module MainStreet
   class << self
     attr_writer :lookup
 
     def lookup
-      @lookup ||= begin
-        if ENV["SMARTY_STREETS_AUTH_ID"] && ENV["SMARTY_STREETS_AUTH_TOKEN"]
-          Geocoder.config[:smarty_streets] ||= {api_key: [ENV["SMARTY_STREETS_AUTH_ID"], ENV["SMARTY_STREETS_AUTH_TOKEN"]]}
-        end
-        Geocoder.config[:smarty_streets] ? :smarty_streets : nil
-      end
+      @lookup ||= ENV["SMARTY_STREETS_AUTH_ID"] ? :smarty_streets : nil
     end
   end
+end
 
-  module Model
-    def acts_as_address(_options = {})
-      class_eval do
-        serialize :original_attributes
-        serialize :verification_info
-
-        validates :street, presence: true
-        validate :verify_address, if: -> { address_fields_changed? }
-        before_save :standardize_address, if: -> { address_fields_changed? }
-
-        def verify_address
-          if zip_code.blank? && (city.blank? || state.blank?)
-            errors.add(:base, "Address can't be confirmed")
-          end
-          if errors.empty?
-            @verification_result = fetch_verification_info
-            if @verification_result
-              if @verification_result.respond_to?(:analysis)
-                case @verification_result.analysis["dpv_match_code"]
-                when "N"
-                  errors.add(:base, "Address can't be confirmed")
-                when "S"
-                  errors.add(:base, "Apartment or suite can't be confirmed")
-                when "D"
-                  errors.add(:base, "Apartment or suite is missing")
-                end
-              end
-
-              correct_zip_code = @verification_result.postal_code
-              if zip_code != correct_zip_code
-                errors.add(:base, "Did you mean #{correct_zip_code}?")
-              end
-            else
-              errors.add(:base, "Address can't be confirmed")
-            end
-          end
-          errors.full_messages
-        end
-
-        def standardize_address
-          result = @verification_result
-          if result
-            info = result.data
-            self.original_attributes = attributes.slice(*address_fields)
-            self.verification_info = result.data.to_hash
-            self.street =
-              if result.respond_to?(:delivery_line_1)
-                result.delivery_line_1
-              else
-                result.formatted_address.split(",").first
-              end
-            self.street2 = nil
-            self.city = result.city
-            self.state = result.state_code
-            self.zip_code = result.postal_code
-            self.latitude = result.latitude
-            self.longitude = result.longitude
-          end
-          true
-        end
-
-        def fetch_verification_info
-          Geocoder.search("#{street} #{street2} #{city}, #{state} #{zip_code}", lookup: Mainstreet.lookup).first
-        end
-
-        def address_fields_changed?
-          address_fields.any? { |f| send("#{f}_changed?") }
-        end
+if ENV["SMARTY_STREETS_AUTH_ID"]
+  Geocoder.config[:smarty_streets] ||= {
+    api_key: [
+      ENV["SMARTY_STREETS_AUTH_ID"],
+      ENV["SMARTY_STREETS_AUTH_TOKEN"]
+    ]
+  }
+end
 
-        def address_fields
-          attributes.keys & %w(street street2 city state zip_code)
-        end
-      end
-    end
+if defined?(ActiveSupport.on_load)
+  ActiveSupport.on_load(:active_record) do
+    require "mainstreet/model"
+    extend MainStreet::Model
   end
 end
-
-ActiveRecord::Base.send(:extend, Mainstreet::Model) if defined?(ActiveRecord)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mainstreet
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.3
 platform: ruby
 authors:
 - Andrew Kane
-autorequire: 
-bindir: exe
+autorequire:
+bindir: bin
 cert_chain: []
-date: 2017-05-01 00:00:00.000000000 Z
+date: 2022-02-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: geocoder
@@ -16,147 +16,32 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.5.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.8'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.8'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '10.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '10.0'
-- !ruby/object:Gem::Dependency
-  name: minitest
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: activerecord
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: sqlite3
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: smartystreets
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: vcr
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: webmock
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-description: A standard US address model for Rails
-email:
-- andrew@chartkick.com
+        version: 1.5.1
+description:
+email: andrew@ankane.org
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
-- Gemfile
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
-- Rakefile
-- lib/generators/mainstreet/address_generator.rb
 - lib/mainstreet.rb
+- lib/mainstreet/address_verifier.rb
+- lib/mainstreet/model.rb
 - lib/mainstreet/version.rb
-- mainstreet.gemspec
 homepage: https://github.com/ankane/mainstreet
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -164,16 +49,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.5.1
-signing_key: 
+rubygems_version: 3.3.3
+signing_key:
 specification_version: 4
-summary: A standard US address model for Rails
+summary: Address verification for Ruby and Rails
 test_files: []

data/.gitignore

@@ -1,10 +0,0 @@
-/.bundle/
-/.yardoc
-/Gemfile.lock
-/_yardoc/
-/coverage/
-/doc/
-/pkg/
-/spec/reports/
-/tmp/
-/test/fixtures/

data/Gemfile

@@ -1,4 +0,0 @@
-source "https://rubygems.org"
-
-# Specify your gem's dependencies in mainstreet.gemspec
-gemspec

data/Rakefile

@@ -1,8 +0,0 @@
-require "bundler/gem_tasks"
-require "rake/testtask"
-
-task default: :test
-Rake::TestTask.new do |t|
-  t.libs << "test"
-  t.pattern = "test/**/*_test.rb"
-end

data/lib/generators/mainstreet/address_generator.rb

@@ -1,10 +0,0 @@
-require "rails/generators"
-
-module Mainstreet
-  class AddressGenerator < Rails::Generators::Base
-    def boom
-      invoke "model", ["Address", "street:string", "street2:string", "city:string", "state:string", "zip_code:string", "latitude:decimal{15.10}", "longitude:decimal{15.10}", "verification_info:text", "original_attributes:text"], options
-      insert_into_file "app/models/address.rb", "  acts_as_address\n", after: "ApplicationRecord\n"
-    end
-  end
-end

data/mainstreet.gemspec

@@ -1,32 +0,0 @@
-# coding: utf-8
-lib = File.expand_path("../lib", __FILE__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require "mainstreet/version"
-
-Gem::Specification.new do |spec|
-  spec.name          = "mainstreet"
-  spec.version       = Mainstreet::VERSION
-  spec.authors       = ["Andrew Kane"]
-  spec.email         = ["andrew@chartkick.com"]
-
-  spec.summary       = "A standard US address model for Rails"
-  spec.description   = "A standard US address model for Rails"
-  spec.homepage      = "https://github.com/ankane/mainstreet"
-  spec.license       = "MIT"
-
-  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
-  spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
-
-  spec.add_dependency "geocoder"
-
-  spec.add_development_dependency "bundler", "~> 1.8"
-  spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency "minitest"
-  spec.add_development_dependency "activerecord"
-  spec.add_development_dependency "sqlite3"
-  spec.add_development_dependency "smartystreets"
-  spec.add_development_dependency "vcr"
-  spec.add_development_dependency "webmock"
-end