mainstreet 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: d572831c5d0c80c6580ac885edf6c1ea8137589d
-  data.tar.gz: 3f50e8e84d9edad8918aa83e9b87ca6f450bc196
+SHA256:
+  metadata.gz: dc0cc69ef3e5d2a656626dc6dca4fc1c2742c302f643f819b84469ee3d3fb5f6
+  data.tar.gz: 8c7b9672fa0129541e76b0013ef3c0b3500d1797ffd1363f8739bfd274deec61
 SHA512:
-  metadata.gz: f9b58c621595ee590c924beb58aa5f4c6402c9df339fc62fd78ea3789ca8ec23accc756f5dabc41a5733c42d98271431db6e1eba007d21ed8dbf2c232fe69134
-  data.tar.gz: 954950d8881fd942e1f159e540eb1634780bb36350720402df09f6f25326490d35e1f38d85f9dd98aa4e2ec0fcf0fccc1d34b5a7024d9dc1d9438ada00558e15
+  metadata.gz: 97261f746dd103d661b8d08d12c3cf9c903aa8e4ddf2b5ce6697e5ecd990ffe77d4557f828ee08ae56499c14b77bdea01cf5a489aa69abd9b1da3dc09debcd7d
+  data.tar.gz: 739008f795c5107cd1a8f41ebebba23a01d992534974294018bdec643f252316246d6f785693b3d31e94733f28a911437f7f55e980c62e3c0c213baf5560db4c

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+## 0.2.0
+
+- Added `AddressVerifier`
+- Added `validates_address` method
+- Removed `acts_as_address` method
+
+## 0.1.0
+
+- Added more validation
+- Fixed model generator for Rails 5
+
+## 0.0.1
+
+- First release

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015 Andrew Kane
+Copyright (c) 2015-2018 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,143 @@
 # MainStreet
 
-A standard US address model for Rails
+Address verification for Ruby and Rails
 
-You get:
+:earth_americas: Supports international addresses
 
-- verification
-- standardization
-- geocoding
+## Installation
 
-## How It Works
+Add this line to your application’s Gemfile:
 
 ```ruby
-Address.create!(street: "1 infinite loop", zip_code: "95014")
+gem 'mainstreet'
 ```
 
-This creates an address with:
+## Full Verification
 
-- 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
+By default, 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:
 
-### Verification
+```ruby
+ENV["SMARTY_STREETS_AUTH_ID"] = "auth-id"
+ENV["SMARTY_STREETS_AUTH_TOKEN"] = "auth-token"
+```
+
+## How to Use
 
-By default, MainStreet performs ZIP code verification.
+Check an address with:
 
 ```ruby
-address = Address.new(street:"1 infinite loop", zip_code: "95015")
-address.valid?
-# false
-address.errors.full_messages
-# ["Did you mean 95014?"]
+address = "1600 Pennsylvania Ave NW, Washington DC 20500"
+verifier = MainStreet::AddressVerifier.new(address)
+verifier.success?
 ```
 
-For full verification, including unit number, [see below](#full-verification).
+If verification fails, get the failure message with:
 
-## Installation
+```ruby
+verifier.failure_message
+```
 
-Add this line to your application’s Gemfile:
+Get details about the result with:
 
 ```ruby
-gem 'mainstreet'
+verifier.result
 ```
 
-To create a new address model, run:
+Get the latitude and longitude with:
 
-```sh
-rails g mainstreet:address
+```ruby
+verifier.latitude
+verifier.longitude
 ```
 
-This creates an `Address` model with:
+## Active Record
 
-- street
-- street2
-- city
-- state
-- zip_code
-- latitude
-- longitude
-- original_attributes
-- verification_info
+For Active Record models, use:
 
-To add to an existing model:
+```ruby
+class User < ApplicationRecord
+  validates_address fields: [:street, :street2, :city, :state, :postal_code]
+end
+```
 
-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
+For performance, the address is only verified if at least one of the fields changes. The order should be the same as if you were to write the address out.
 
-## Full Verification
+Geocode the address 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: true, ...
+end
+```
 
-Set:
+The `latitude` and `longitude` fields are used by default. Specify the fields with:
 
 ```ruby
-ENV["SMARTY_STREETS_AUTH_ID"] = "auth-id"
-ENV["SMARTY_STREETS_AUTH_TOKEN"] = "auth-token"
+class User < ApplicationRecord
+  validates_address geocode: {latitude: :lat, longitude: :lon}, ...
+end
+```
+
+Empty addresses are not verified. To require an address, add your own validation.
+
+```ruby
+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`).
+
+**Note:** You’ll also need to use a fork of Geocoder until [this PR](https://github.com/alexreisner/geocoder/pull/1367) is merged.
 
 ```ruby
-address = Address.new(street: "122 Mast Rd", zip_code: "03861")
-address.valid?
-# should get false
+gem 'geocoder', github: 'ankane/geocoder', branch: 'smarty_streets_international'
 ```
 
+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
+```
+
+## Data Privacy
+
+We recommend encrypting the street information for user addresses. Check out [this article](https://ankane.org/sensitive-data-rails) for more details.
+
+```ruby
+class User < ApplicationRecord
+  attr_encrypted :street, key: ...
+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:

data/lib/mainstreet.rb

@@ -1,95 +1,22 @@
-require "mainstreet/version"
+# dependencies
 require "geocoder"
 
-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
-    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
+# modules
+require "mainstreet/address_verifier"
+require "mainstreet/version"
 
-        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)

data/lib/mainstreet/address_verifier.rb

@@ -0,0 +1,70 @@
+module MainStreet
+  class AddressVerifier
+    def initialize(address, country: nil)
+      @address = address
+      @country = country
+    end
+
+    def success?
+      failure_message.nil?
+    end
+
+    def failure_message
+      if !result
+        "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"
+            "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"
+            "Address can't be confirmed"
+          when "S"
+            "Apartment or suite can't be confirmed"
+          when "D"
+            "Apartment or suite is missing"
+          else
+            raise "Unknown dpv_match_code"
+          end
+        end
+      end
+    end
+
+    def result
+      @result ||= begin
+        options = {lookup: lookup}
+        options[:country] = @country if @country && !usa?
+        Geocoder.search(@address, options).first
+      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 lookup
+      ENV["SMARTY_STREETS_AUTH_ID"] ? :smarty_streets : nil
+    end
+  end
+end

data/lib/mainstreet/model.rb

@@ -0,0 +1,34 @@
+module MainStreet
+  module Model
+    def validates_address(fields:, geocode: false, country: nil)
+      fields = Array(fields.map(&:to_s))
+      geocode_options = {latitude: :latitude, longitude: :longitude}
+      geocode_options = geocode_options.merge(geocode) if geocode.is_a?(Hash)
+
+      class_eval do
+        validate :verify_address, if: -> { fields.any? { |f| changes.key?(f.to_s) } }
+
+        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.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mainstreet
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Andrew Kane
 autorequire: 
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2017-05-01 00:00:00.000000000 Z
+date: 2018-12-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: geocoder
@@ -28,32 +28,18 @@ dependencies:
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.8'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.8'
+        version: '0'
 - !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:
     - - ">="
@@ -67,7 +53,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: activerecord
+  name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -81,7 +67,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: sqlite3
+  name: activerecord
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -95,7 +81,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: smartystreets
+  name: sqlite3
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -136,22 +122,19 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: A standard US address model for Rails
-email:
-- andrew@chartkick.com
+description: 
+email: andrew@chartkick.com
 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
@@ -164,7 +147,7 @@ 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:
   - - ">="
@@ -172,8 +155,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.7.6
 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