opencnam 0.0.1 → 1.0.0

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2013 Nysa Vann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,78 @@
+# ruby-opencnam
+
+A Ruby wrapper for the [OpenCNAM](http://www.opencnam.com/) API service.
+
+ruby-opencnam v1.0.0 only supports OpenCNAM API v2. For more information see:
+https://www.opencnam.com/docs/v2
+
+## Installation
+
+Install from [RubyGems](http://rubygems.org/):
+
+    $ gem install opencnam
+
+Or include it in your `Gemfile` and install via Bundler's `bundle install`:
+
+    gem 'opencnam'
+
+## Usage
+
+Simplest example:
+
+    require 'opencnam'
+
+    client = Opencnam::Client.new
+
+    client.phone('7731234567')
+    # => 'VANN,NYSA'
+
+    client.phone('7731234567', :format => :json)
+    # => {:number=>"+17731234567", :uri=>"/v2/phone/%2B17731234567",
+    #     :price=>0, :name=>"VANN,NYSA", :created=>2012-10-05 19:36:33 -0500,
+    #     :updated=>2012-10-05 19:36:33 -0500}
+
+## Notes
+
+### Hobbyist Plan
+Sending more than 60 requests within an hour without specifying a `account_sid` and `auth_token` will result in a 403 status code and raise an `Opencnam::OpencnamError`.
+
+### Professional Plan
+You can configure `ruby-opencnam` to use your `account_sid` and `auth_token`:
+
+    client = Opencnam::Client.new(
+      :account_sid => 'your_account_sid',
+      :auth_token => 'your_auth_token',
+    )
+
+or
+
+    client = Opencnam::Client.new
+    client.account_sid = 'your_account_sid'
+    client.auth_token = 'your_auth_token'
+
+### SSL
+You can send configure `ruby-opencnam` to send requests over SSL:
+
+    client = Opencnam::Client.new(:use_ssl => true)
+
+    # or
+
+    client = Opencnam::Client.new
+    client.use_ssl = true
+
+    # Check if SSL is set
+    client.use_ssl?
+    # => true
+
+### Opencnam::OpencnamError
+Calling the `phone` method can raise an `Opencnam::OpencnamError` for a variety of reasons (not found, bad request, payment required, etc.). For a full list of things that can go wrong, see:
+https://www.opencnam.com/docs/v2/apiref#cnam-status-codes
+
+### Returned name formats
+The name returned from OpenCNAM varies. Sometimes not providing a name at all and instead providing just a city and state such as `'SACRAMENTO CA'`. Sometimes names can get cut off, like `'VANN,NYS'`. Take caution if you plan on parsing names!
+
+## License
+
+Copyright &copy; 2013 Nysa Vann <<nysa@nysavann.com>>
+
+ruby-opencnam is distributed under an MIT-style license. See LICENSE for details.

data/lib/opencnam.rb

@@ -1,79 +1,7 @@
-require "net/http"
+require 'date'
+require 'json'
+require 'net/http'
 
-require "opencnam/version"
-require "opencnam/util"
-require "opencnam/errors/opencnam_error"
-require "opencnam/errors/bad_request_error"
-require "opencnam/errors/invalid_phone_number_error"
-require "opencnam/errors/no_info_error"
-require "opencnam/errors/running_lookup_error"
-require "opencnam/errors/throttled_error"
-
-module OpenCNAM
-  @@api_base = 'https://api.opencnam.com'
-  @@api_user = nil
-  @@api_key  = nil
-
-  def self.api_user=(api_user)
-    @@api_user = api_user
-  end
-
-  def self.api_key=(api_key)
-    @@api_key = api_key
-  end
-
-  def self.lookup(number)
-    # Clean phone number
-    clean_number = OpenCNAM::Util.clean_phone_number(number)
-
-    # Build query
-    query = URI.encode_www_form(
-      :format => 'text',
-      :username => @@api_user,
-      :api_key => @@api_key,
-    )
-
-    # Send request
-    uri = URI.parse(@@api_base)
-    http = Net::HTTP.new(uri.host, uri.port)
-    http.use_ssl = true
-
-    res = http.request_get("/v1/phone/#{clean_number}?#{query}")
-
-    # 200 - OK
-    if res.kind_of?(Net::HTTPOK)
-      return {
-        :name => res.body,
-        :number => clean_number,
-      }
-    end
-
-    error_attrs = {
-      :http_status => res.code,
-      :message => res.message,
-    }
-
-    # 202 - Currently running a lookup for phone number
-    if res.kind_of?(Net::HTTPAccepted)
-      raise RunningLookupError.new(error_attrs)
-    end
-
-    # 403 - Forbidden, requests throttled
-    if res.kind_of?(Net::HTTPForbidden)
-      raise ThrottledError.new(error_attrs)
-    end
-
-    # 400 - Bad request
-    if res.kind_of?(Net::HTTPBadRequest)
-      raise BadRequestError.new(error_attrs)
-    end
-
-    # 404 - No caller ID name information
-    if res.kind_of?(Net::HTTPNotFound)
-      raise NoInfoError.new(error_attrs)
-    end
-
-    # Unkown response
-    raise OpenCNAMError.new(error_attrs)
-  end
-end
+require 'opencnam/client'
+require 'opencnam/opencnam_error'
+require 'opencnam/parsers'

data/lib/opencnam/client.rb

@@ -0,0 +1,78 @@
+require 'opencnam/parsers'
+
+module Opencnam #:nodoc:
+  # :nodoc:
+  # @!attribute [rw] account_sid
+  #   @return [String] the account_sid
+  # @!attribute [rw] auth_token
+  #   @return [String] the auth_token
+  # @!attribute [w] use_ssl
+  #   @return [Boolean]
+  class Client
+    # The OpenCNAM API hostname
+    API_HOST = 'api.opencnam.com'
+    include Parsers
+
+    attr_writer :use_ssl
+    attr_accessor :account_sid, :auth_token
+
+    # @param [Hash] options
+    # @option options [String] :account_sid (nil)
+    # @option options [String] :auth_token (nil)
+    # @option options [Boolean] :use_ssl (false)
+    def initialize(options = {})
+      @account_sid = options[:account_sid].strip if options[:account_sid]
+      @auth_token = options[:auth_token].strip if options[:auth_token]
+      @use_ssl = options[:use_ssl]
+    end
+
+    # Returns true if this client instance is configured to use SSL by
+    # default.
+    #
+    # @return [Boolean]
+    def use_ssl?
+      @use_ssl
+    end
+
+    # Look up a phone number and return the caller's name.
+    #
+    # @param [String] phone_number The phone number to look up
+    # @param [Hash] options Described below
+    # @option options [String] :account_sid Specify a different OpenCNAM
+    #   account_sid
+    # @option options [String] :auth_token Specify a different OpenCNAM
+    #   auth_token
+    # @option options [String, Symbol] :format (:text) The format to retrieve,
+    #   can be :text or :json
+    # @return [String, Hash] the phone number owner's name if :format is
+    #   :string, or a Hash of additional fields from OpenCNAM if :format
+    #   is :json (:created, :updated, :name, :price, :uri, and
+    #   :number)
+    def phone(phone_number, options = {})
+      # Build query string
+      options = {
+        :account_sid => account_sid,
+        :auth_token => auth_token,
+        :format => 'text',
+      }.merge(options)
+      options[:format] = options[:format].to_s.strip.downcase
+
+      # Check for supported format
+      unless %w(text json).include? options[:format]
+        raise ArgumentError.new "Unsupported format: #{options[:format]}"
+      end
+
+      # Send request
+      http = Net::HTTP.new(API_HOST, (use_ssl? ? '443' : '80'))
+      http.use_ssl = true if use_ssl?
+      query = URI.encode_www_form(options)
+      res = http.request_get("/v2/phone/#{phone_number.strip}?#{query}")
+
+      # Look up was unsuccessful
+      raise OpencnamError.new res.message unless res.kind_of? Net::HTTPOK
+
+      return res.body if options[:format] == 'text'
+      return parse_json(res.body) if options[:format] == 'json'
+    end
+  end
+end

data/lib/opencnam/opencnam_error.rb

@@ -0,0 +1,4 @@
+module Opencnam #:nodoc:
+  class OpencnamError < StandardError #:nodoc:
+  end
+end

data/lib/opencnam/parsers.rb

@@ -0,0 +1,33 @@
+module Opencnam #:nodoc:
+  # Contains utility methods for parsing responses from OpenCNAM.
+  module Parsers
+    private
+
+    # Parses an ISO 8601 formatted date string.
+    # @param [String] date_string
+    # @return [Time]
+    def parse_iso_date_string(date_string)
+      DateTime.iso8601(date_string).to_time
+    rescue ArgumentError
+      nil
+    end
+
+    # Parses a JSON string.
+    # @param [String] json the JSON formatted string
+    # @return [Hash]
+    def parse_json(json)
+      hash = JSON.parse(json, :symbolize_names => true)
+
+      # Convert hash[:created] and hash[:updated] to Time objects
+      if hash[:created]
+        hash.merge!({ :created => parse_iso_date_string(hash[:created]) })
+      end
+
+      if hash[:updated]
+        hash.merge!({ :updated => parse_iso_date_string(hash[:updated]) })
+      end
+
+      hash
+    end
+  end
+end

data/lib/opencnam/version.rb

@@ -1,3 +1,3 @@
-module OpenCNAM
-  VERSION = '0.0.1'
+module Opencnam #:nodoc:
+  VERSION = '1.0.0' #:nodoc:
 end

data/spec/fixtures/opencnam_bad_response.rb

@@ -0,0 +1,12 @@
+class OpencnamBadResponse < Net::HTTPBadRequest
+  def body
+    ''
+  end
+
+  def initialize
+  end
+
+  def message
+    'Bad request'
+  end
+end

data/spec/fixtures/opencnam_ok_response.rb

@@ -0,0 +1,12 @@
+class OpencnamOkResponse < Net::HTTPOK
+  def body
+    '{ "uri": "/v2/phone/%2B16502530000", "price": 0, "updated": "2013-02-17T01:34:22.501327", "name": "GOOGLE INC", "created": "2012-10-12T06:53:05.194858", "number": "+16502530000"}'
+  end
+
+  def initialize
+  end
+
+  def message
+    'OK'
+  end
+end

data/spec/lib/opencnam/client_spec.rb

@@ -0,0 +1,92 @@
+require 'spec_helper'
+
+describe Opencnam::Client do
+  let(:client) { Opencnam::Client.new }
+
+  describe '#initialize' do
+    context 'when options is not given' do
+      it 'should set @use_ssl to false' do
+        client.use_ssl?.should be_false
+      end
+
+      it 'should set @account_sid to nil' do
+        client.account_sid.should be_nil
+      end
+
+      it 'should set @auth_token to nil' do
+        client.auth_token.should be_nil
+      end
+    end
+
+    context 'when options is given' do
+      let(:options) { {
+        :account_sid => 'example-account-sid ',
+        :auth_token => 'example-auth-token',
+        :use_ssl => true,
+      } }
+      let(:client) { Opencnam::Client.new(options) }
+
+      it 'should set @use_ssl' do
+        client.use_ssl?.should be_true
+      end
+
+      it 'should set @account_sid' do
+        client.account_sid.should_not be_nil
+      end
+
+      it 'should set @auth_token' do
+        client.auth_token.should_not be_nil
+      end
+    end
+  end
+
+  describe '#use_ssl?' do
+    context 'when @use_ssl is true' do
+      it 'should return true' do
+        client.use_ssl = true
+        client.use_ssl?.should be_true
+      end
+    end
+
+    context 'when @use_ssl is false' do
+      it 'should return false' do
+        client.use_ssl = false
+        client.use_ssl?.should be_false
+      end
+    end
+  end
+
+  describe '#phone' do
+    it 'should return a String' do
+      client.phone('+16502530000')
+    end
+
+    context 'when given a bad phone number' do
+      it 'should raise OpencnamError' do
+        expect { client.phone('+abcdefgh') }.to(
+          raise_error Opencnam::OpencnamError
+        )
+      end
+    end
+
+    context 'when given :format => :text' do
+      it 'should return a String' do
+        client.phone('+16502530000', :format => :text).should be_a String
+      end
+    end
+
+    context 'when given :format => :json' do
+      it 'should return a Hash' do
+        client.phone('+16502530000', :format => :json).should be_a Hash
+      end
+    end
+
+    context 'when given an unsupported :format' do
+      it 'should raise ArgumentError' do
+        expect { client.phone('+16502530000', :format => :xml) }.to(
+          raise_error ArgumentError
+        )
+      end
+    end
+  end
+end

data/spec/lib/opencnam/parsers_spec.rb

@@ -0,0 +1,60 @@
+require 'spec_helper'
+
+class DummyExtender
+  extend Opencnam::Parsers
+end
+
+describe Opencnam::Parsers do
+  describe '#parse_iso_date_string' do
+    context 'when given a valid ISO date string' do
+      it 'should return a Time object' do
+        string = '2013-02-17T01:34:22.501327'
+        DummyExtender.send(:parse_iso_date_string, string).should be_a Time
+      end
+    end
+
+    context 'when given an invalid string' do
+      it 'should return nil' do
+        DummyExtender.send(:parse_iso_date_string, 'abcdef').should eq nil
+      end
+    end
+
+    context 'when given nil' do
+      it 'should return nil' do
+        DummyExtender.send(:parse_iso_date_string, nil).should be_nil
+      end
+    end
+  end
+
+  describe '#parse_json' do
+    it 'should return a Hash' do
+      DummyExtender.send(:parse_json, '{"name":"Nysa"}').should be_a Hash
+    end
+
+    it 'should not receive #parse_iso_date_string' do
+      DummyExtender.should_not_receive(:parse_iso_date_string)
+      DummyExtender.send(:parse_json, '{"name":"Nysa"}')
+    end
+
+    context 'when given a JSON string with key created' do
+      it 'should receive #parse_iso_date_string' do
+        DummyExtender.should_receive(:parse_iso_date_string)
+        DummyExtender.send(:parse_json, '{"created":"ISO"}')
+      end
+    end
+
+    context 'when given a JSON string with key updated' do
+      it 'should receive #parse_iso_date_string' do
+        DummyExtender.should_receive(:parse_iso_date_string)
+        DummyExtender.send(:parse_json, '{"updated":"ISO"}')
+      end
+    end
+
+    context 'when given a JSON string with keys updated and created' do
+      it 'should receive #parse_iso_date_string twice' do
+        DummyExtender.should_receive(:parse_iso_date_string).twice
+        DummyExtender.send(:parse_json, '{"created":"ISO","updated":"ISO"}')
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,11 @@
+$:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'opencnam'
+require 'rspec'
+
+# Load fixtures
+load File.join(File.dirname(__FILE__), 'fixtures', 'opencnam_ok_response.rb')
+load File.join(File.dirname(__FILE__), 'fixtures', 'opencnam_bad_response.rb')
+
+RSpec.configure do |config|
+  config.mock_with :rspec
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: opencnam
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,56 +9,56 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-06-21 00:00:00.000000000 Z
+date: 2013-03-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: fakeweb
+  name: json
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '1.3'
-  type: :development
+        version: 1.7.7
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: 1.7.7
 - !ruby/object:Gem::Dependency
-  name: minitest
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: 3.1.0
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: 3.1.0
+        version: '0'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: rspec
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 2.12.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 2.12.0
 description: OpenCNAM provides a simple, elegant, and RESTful API to get Caller ID
   data.
 email: nysa@nysavann.com
@@ -66,17 +66,21 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/opencnam/errors/bad_request_error.rb
-- lib/opencnam/errors/invalid_phone_number_error.rb
-- lib/opencnam/errors/no_info_error.rb
-- lib/opencnam/errors/opencnam_error.rb
-- lib/opencnam/errors/running_lookup_error.rb
-- lib/opencnam/errors/throttled_error.rb
-- lib/opencnam/util.rb
+- LICENSE
+- README.md
+- lib/opencnam/client.rb
+- lib/opencnam/opencnam_error.rb
+- lib/opencnam/parsers.rb
 - lib/opencnam/version.rb
 - lib/opencnam.rb
+- spec/fixtures/opencnam_bad_response.rb
+- spec/fixtures/opencnam_ok_response.rb
+- spec/lib/opencnam/client_spec.rb
+- spec/lib/opencnam/parsers_spec.rb
+- spec/spec_helper.rb
 homepage: http://github.com/nysa/ruby-opencnam
-licenses: []
+licenses:
+- MIT
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -95,8 +99,13 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.22
+rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
 summary: Ruby bindings for the OpenCNAM API
-test_files: []
+test_files:
+- spec/fixtures/opencnam_bad_response.rb
+- spec/fixtures/opencnam_ok_response.rb
+- spec/lib/opencnam/client_spec.rb
+- spec/lib/opencnam/parsers_spec.rb
+- spec/spec_helper.rb

data/lib/opencnam/errors/bad_request_error.rb

@@ -1,4 +0,0 @@
-module OpenCNAM
-  class BadRequestError < OpenCNAMError
-  end
-end

data/lib/opencnam/errors/invalid_phone_number_error.rb

@@ -1,7 +0,0 @@
-module OpenCNAM
-  class InvalidPhoneNumberError < OpenCNAMError
-    def initialize(phone_number)
-      super(:message => "#{phone_number} could not be parsed as a valid US phone number")
-    end
-  end
-end

data/lib/opencnam/errors/no_info_error.rb

@@ -1,4 +0,0 @@
-module OpenCNAM
-  class NoInfoError < OpenCNAMError
-  end
-end

data/lib/opencnam/errors/opencnam_error.rb

@@ -1,18 +0,0 @@
-module OpenCNAM
-  class OpenCNAMError < StandardError
-    attr_reader :message
-    attr_reader :http_status
-    attr_reader :http_body
-
-    def initialize(opts = {})
-      @message = opts[:message] || nil
-      @http_status = opts[:http_status] || nil
-      @http_body = opts[:http_body] || nil
-    end
-
-    def to_s
-      status = @http_status.nil? ? "" : "(Status #{@http_status}) "
-      "#{status}#{@message}"
-    end
-  end
-end

data/lib/opencnam/errors/running_lookup_error.rb

@@ -1,4 +0,0 @@
-module OpenCNAM
-  class RunningLookupError < OpenCNAMError
-  end
-end

data/lib/opencnam/errors/throttled_error.rb

@@ -1,4 +0,0 @@
-module OpenCNAM
-  class ThrottledError < OpenCNAMError
-  end
-end

data/lib/opencnam/util.rb

@@ -1,14 +0,0 @@
-module OpenCNAM
-  module Util
-    def self.clean_phone_number(number)
-      # Drop all characters except integers
-      clean_number = number.to_s
-      clean_number.tr!('^0-9', '')
-      clean_number = clean_number[-10..-1]
-
-      raise InvalidPhoneNumberError.new(number) if !clean_number || clean_number.length < 10
-
-      clean_number
-    end
-  end
-end