telein-client 0.1.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1 @@
+--color --format documentation

data/.yardopts

@@ -0,0 +1,4 @@
+--title "Telein::Client Documentation"
+--protected
+--markup-provider=redcarpet
+--markup=markdown

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2013 Thiago Brandão Damasceno
+
+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,62 @@
+# Telein::Client
+
+The 'telein-client' gem allows the access for
+the Telein API in Ruby.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'telein-client', :require => 'telein'
+
+Or install it yourself as:
+
+    $ gem install telein-client
+
+## Usage
+
+    require 'telein'
+
+    # if you do not set this properly, it's going to return 999 responses
+    Telein.api_key = 'your_api_key'
+
+    client = Telein::Client.new
+    client.carrier_code_for('(12) 3434-5656') # => 41
+
+## About Telein
+
+[Telein](http://www.telein.com.br/) is a service that
+allows the fetching of carrier codes for Brazilian phones,
+through simple GET requests to its servers.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## MIT License
+
+Copyright (c) 2013 Thiago Brandão Damasceno
+
+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/Rakefile

@@ -0,0 +1,34 @@
+# encoding: utf-8
+
+require 'rubygems'
+
+begin
+  require 'bundler'
+rescue LoadError => e
+  warn e.message
+  warn "Run `gem install bundler` to install Bundler."
+  exit -1
+end
+
+begin
+  Bundler.setup(:development)
+rescue Bundler::BundlerError => e
+  warn e.message
+  warn "Run `bundle install` to install missing gems."
+  exit e.status_code
+end
+
+require 'rake'
+
+require 'rubygems/tasks'
+Gem::Tasks.new
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new
+
+task :test    => :spec
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new
+task :doc => :yard

data/lib/telein/carrier_codes.rb

@@ -0,0 +1,24 @@
+# encoding: utf-8
+module Telein
+  # The mapping of carrier codes and meanings , in pt-BR
+  # @todo Maybe provide in en-US format
+  CARRIER_CODES = {
+    12  => "CTBC",
+    14  => "Brasil Telecom",
+    20  => "Vivo",
+    21  => "Claro",
+    23  => "Telemig",
+    24  => "Amazonia",
+    31  => "Oi",
+    37  => "Unicel",
+    41  => "TIM",
+    43  => "Sercomercio",
+    77  => "Nextel",
+    98  => "Fixo",
+    99  => "Número não encontrado",
+    100 => "Número inválido",
+    101 => "Erro no servidor",
+    990 => "IP blacklisted",
+    995 => "IP excedeu 6 consultas/hora nas últimas 24 horas",
+    999 => "Chave inválida" }
+end

data/lib/telein/client.rb

@@ -0,0 +1,69 @@
+# encoding: utf-8
+require 'curb'
+
+module Telein
+  # Class used to query Telein servers for carrier codes
+  #
+  # No API key given
+  # ----------------
+  # The client doesn't make any request if the {Telein#api_key API key}
+  # is missing, returning a 999 code immediately.
+  #
+  # Invalid phones
+  # --------------
+  # Telein can tell if a given phone is invalid but each
+  # request is a credit spent so the class also encapsulates
+  # the code from Telein::Util::Phone to detect invalid ones
+  # preemptively.
+  #
+  # All servers down
+  # ----------------
+  # If all {Telein#register_server Registered servers} are
+  # down, then the client return 101 for carrier_code
+  #
+  # @example Query servers for the carrier code of a given phone
+  #    client = Telein::Client.new
+  #    client.carrier_code_for('(12) 3434-5656') # => '41'
+  class Client
+
+    # Queries the Telein servers for the carrier code of value
+    #
+    # @param value [String] A string supposedly containing phone information
+    # @return [Integer] The carrier code for value
+    def carrier_code_for(value)
+      return 999 unless Telein.api_key
+
+      phone = Telein::Util::Phone.new(value)
+
+      if phone.valid?
+        Telein.servers.each do |server|
+          begin
+            curl = Curl::Easy.new do |easy|
+              easy.url = server.query_url_for(phone.to_telein_s)
+            end
+
+            # client request
+            curl.http_get
+
+            # telein response
+            response = curl.body_str
+
+            # response parsing (carrier#number)
+            carrier_code, _ = response.split('#')
+
+            return carrier_code.to_i
+          rescue
+            next
+          end
+        end
+
+        # all servers down
+        return 101
+      else
+        # invalid phone
+        return 100
+      end
+    end
+
+  end
+end

data/lib/telein/server.rb

@@ -0,0 +1,35 @@
+require 'uri'
+
+module Telein
+  # The class that encapsulates all code that build
+  # request queries made to Telein servers by the client
+  #
+  # @example Instantiate a server and build a query for phone
+  #   server = Telein::Server.new('consultanumero1.telein.com.br')
+  #   server.query_url_for('1234345656')
+  #   => 'http://consultanumero1.telein.com.br/sistema/consulta_numero.php?numero=1234345656&chave=my_api_key'
+  class Server
+    # Gets/sets the endpoint (an URL) representing
+    # a Telein Server
+    #
+    # @return [String] the endpoint
+    attr_accessor :endpoint
+
+    # @param endpoint [String] The URL of the server
+    def initialize(endpoint)
+      self.endpoint = endpoint
+    end
+
+    # Builds a request URL to be used by the client to fetch the carrier code
+    #
+    # @param phone [String] A phone in the {Telein::Util::Phone#to_telein_s Telein format}
+    # @return [String] A URL the client will use to fetch the carrier code
+    # @see Telein::Client#carrier_code_for
+    def query_url_for(phone)
+      url = URI::HTTP.build({:host  => self.endpoint,
+                             :path  => '/sistema/consulta_numero.php',
+                             :query => URI::encode_www_form({:numero => phone,:chave => Telein.api_key})})
+      url.to_s
+    end
+  end
+end

data/lib/telein/util/phone.rb

@@ -0,0 +1,81 @@
+module Telein
+  # Utility classes
+  module Util
+    # Class that encapsulates phone data logic
+    class Phone
+
+      # The Matching parts of Phone::FORMAT
+      #
+      # @return [MatchData] A +MatchData+ object containing the matching made against value
+      # @see #initialize
+      attr_reader :matching
+
+      # General format of a Brazilian phone.
+      # An area_code and a number that may contain and extra 9
+      FORMAT = /\A\(?(?<area_code>[1-9][0-9])\)?\s*(?<number>(?<extra_digit>9?)[2-9]\d{3}\-?\d{4})\Z/
+
+      # @param value [String] a string containing phone information
+      def initialize(value)
+        @matching = value.match(FORMAT) if value
+      end
+
+      # Returns a string ready to be consumed by Telein API
+      # @example Return a formatted phone
+      #   phone = Telein::Util::Phone.new('(12) 3434-5656')
+      #   phone.to_telein_s # => '1234345656'
+      #
+      # @return [String] a string in Telein format
+      def to_telein_s
+        return nil.to_s unless self.valid?
+
+        [self.area_code,self.number].join
+      end
+
+      # Returns the area code for phone
+      #
+      # @return [String] the area code of phone
+      def area_code
+        self.matching[:area_code] if self.matching
+      end
+
+      # Returns the number part of phone (everything minus area code)
+      #
+      # @return [String] the number part of phone
+      def number
+        self.matching[:number].delete('-') if self.matching
+      end
+
+      # Checks if phone has an extra digit
+      # The extra digit '9' was introduced only to phones
+      # in 11 area code (São Paulo) to account for new phones
+      #
+      # @return [Boolean] whether phone has an extra 9
+      def has_extra_digit?
+        return false unless self.matching
+        self.matching[:extra_digit] == '9' ? true : false
+      end
+
+      # Checks if phone is valid
+      # This is a loosen check, in the sense that it accepts
+      # a wide range of probably invalid phones, like
+      # (99) 9999-9999 but the specs for area codes in Brazil
+      # are also loosen, allowing the existence of such numbers in the future.
+      # Also, for phones in the 11 area, the method may return false
+      # positives, since only cellphones have that extra digit.
+      #
+      # @return [Boolean] whether phone is valid or invalid
+      def valid?
+        if self.area_code && self.number
+          if self.has_extra_digit? && self.area_code != '11'
+            false
+          else
+            true
+          end
+        else
+          false
+        end
+      end
+
+    end
+  end
+end

data/lib/telein/version.rb

@@ -0,0 +1,4 @@
+module Telein
+  # Telein version
+  VERSION = "0.1.0"
+end

data/lib/telein.rb

@@ -0,0 +1,36 @@
+# Namespace for classes and modules that handle the Telein API
+module Telein
+  extend self
+
+  # Gets/sets api key to access Telein API
+  # @return [String]
+  attr_accessor :api_key
+
+  # An array of servers available to be requested
+  # by the client. The client will use the response
+  # of the first one that responds the request.
+  # @see Telein::Client#carrier_code_for
+  #
+  # @return [Array<Telein::Server>]
+  def servers
+    @servers ||= []
+  end
+
+  # Syntax sugar for the {Array#<<} method.
+  #
+  # @return [Array<Telein::Server>]
+  def register_server(server)
+    self.servers << server
+  end
+end
+
+require 'telein/version'
+require 'telein/carrier_codes'
+require 'telein/util/phone'
+require 'telein/server'
+require 'telein/client'
+
+# @see Telein::Server#initialize
+Telein.register_server(Telein::Server.new('consultanumero1.telein.com.br'))
+Telein.register_server(Telein::Server.new('consultanumero2.telein.com.br'))
+Telein.register_server(Telein::Server.new('consultanumero3.telein.com.br'))

data/spec/spec_helper.rb

@@ -0,0 +1,7 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'telein'
+require 'rspec'
+require 'webmock'
+require 'webmock/rspec'

data/spec/telein/client_spec.rb

@@ -0,0 +1,54 @@
+require 'spec_helper'
+
+describe Telein::Client do
+
+  before(:each) do
+    Telein.api_key = 'my_api_key'
+  end
+
+  after(:each) do
+    WebMock.reset!
+  end
+
+  it 'returns 999 when no api key is provided' do
+    Telein.api_key = nil
+
+    Telein.servers.each do |server|
+      stub_request(:get,server.query_url_for('0000000000')).to_return(:body => '99#0000000000')
+      stub_request(:get,server.query_url_for('1234345656')).to_return(:body => '98#1234345656')
+      stub_request(:get,server.query_url_for('1294345656')).to_return(:body => '41#1294345656')
+    end
+
+    client = described_class.new
+    client.carrier_code_for('(00) 0000-0000').should == 999
+    client.carrier_code_for('(12) 3434-5656').should == 999
+    client.carrier_code_for('(12) 9434-5656').should == 999
+  end
+
+  it 'returns carrier codes' do
+    Telein.servers.each do |server|
+      stub_request(:get,server.query_url_for('0000000000')).to_return(:body => '99#0000000000')
+      stub_request(:get,server.query_url_for('1234345656')).to_return(:body => '98#1234345656')
+      stub_request(:get,server.query_url_for('1294345656')).to_return(:body => '41#1294345656')
+    end
+
+    client = described_class.new
+    client.carrier_code_for('(00) 0000-0000').should == 100
+    client.carrier_code_for('(12) 3434-5656').should == 98
+    client.carrier_code_for('(12) 9434-5656').should == 41
+  end
+
+  it 'returns server error code when all endpoints are down' do
+    Telein.servers.each do |server|
+      stub_request(:get,server.query_url_for('0000000000')).to_timeout
+      stub_request(:get,server.query_url_for('1234345656')).to_timeout
+      stub_request(:get,server.query_url_for('1294345656')).to_timeout
+    end
+
+    client = described_class.new
+    client.carrier_code_for('(00) 0000-0000').should == 100
+    client.carrier_code_for('(12) 3434-5656').should == 101
+    client.carrier_code_for('(12) 9434-5656').should == 101
+  end
+
+end

data/spec/telein/server_spec.rb

@@ -0,0 +1,16 @@
+require 'spec_helper'
+require 'uri'
+
+describe Telein::Server do
+
+  it 'returns query url for a given phone' do
+    Telein.api_key = 'my_api_key'
+    endpoint       = 'consultanumero1.telein.com.br'
+    phone          = '1234345656'
+
+    server = described_class.new(endpoint)
+
+    server.query_url_for(phone).should == 'http://consultanumero1.telein.com.br/sistema/consulta_numero.php?numero=1234345656&chave=my_api_key'
+  end
+
+end

data/spec/telein/util/phone_spec.rb

@@ -0,0 +1,39 @@
+require 'spec_helper'
+
+describe Telein::Util::Phone do
+
+  it 'rejects invalid phones' do
+    phone = described_class.new('anything')
+    phone.number.should be_nil
+    phone.area_code.should be_nil
+    expect(phone.has_extra_digit?).to be_false
+    expect(phone.valid?).to be_false
+
+    phone = described_class.new('(12) 3434-5656')
+    phone.number.should == '34345656'
+    phone.area_code.should == '12'
+    expect(phone.has_extra_digit?).to be_false
+    expect(phone.valid?).to be_true
+
+    phone = described_class.new('(21) 9434-5656')
+    phone.number.should == '94345656'
+    phone.area_code.should == '21'
+    expect(phone.has_extra_digit?).to be_false
+    expect(phone.valid?).to be_true
+
+    phone = described_class.new('(21) 99434-5656')
+    phone.number.should == '994345656'
+    phone.area_code.should == '21'
+    expect(phone.has_extra_digit?).to be_true
+    expect(phone.valid?).to be_false
+  end
+
+  it 'returns format for telein purposes' do
+    phone = described_class.new('(21) 9434-5656')
+    phone.to_telein_s.should == '2194345656'
+
+    phone = described_class.new('2194345656')
+    phone.to_telein_s.should == '2194345656'
+  end
+
+end

data/telein-client.gemspec

@@ -0,0 +1,31 @@
+# encoding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'telein/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "telein-client"
+  gem.version       = Telein::VERSION
+  gem.summary       = %q{Client to access Telein API in Ruby}
+  gem.description   = %q{The 'telein-client' gem allows the access for
+the Telein API in Ruby.}
+  gem.license       = "MIT"
+  gem.authors       = ["Thiago Brandão Damasceno"]
+  gem.email         = "thiagobrandam@gmail.com"
+  gem.homepage      = "https://github.com/thiagobrandam/telein-client#readme"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ['lib']
+
+  gem.add_dependency 'curb', '~> 0.8'
+
+  gem.add_development_dependency 'bundler', '~> 1.0'
+  gem.add_development_dependency 'rake', '~> 0.9'
+  gem.add_development_dependency 'redcarpet'
+  gem.add_development_dependency 'rspec', '~> 2.13.0'
+  gem.add_development_dependency 'rubygems-tasks', '~> 0.2'
+  gem.add_development_dependency 'webmock', '~> 1.11'
+  gem.add_development_dependency 'yard', '~> 0.8'
+end

metadata

@@ -0,0 +1,203 @@
+--- !ruby/object:Gem::Specification
+name: telein-client
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Thiago Brandão Damasceno
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-03-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: curb
+  prerelease: false
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  prerelease: false
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  prerelease: false
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  prerelease: false
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  prerelease: false
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.13.0
+  type: :development
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.13.0
+- !ruby/object:Gem::Dependency
+  name: rubygems-tasks
+  prerelease: false
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :development
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  prerelease: false
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.11'
+  type: :development
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.11'
+- !ruby/object:Gem::Dependency
+  name: yard
+  prerelease: false
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.8'
+description: ! 'The ''telein-client'' gem allows the access for
+
+  the Telein API in Ruby.'
+email: thiagobrandam@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- .yardopts
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/telein.rb
+- lib/telein/carrier_codes.rb
+- lib/telein/client.rb
+- lib/telein/server.rb
+- lib/telein/util/phone.rb
+- lib/telein/version.rb
+- spec/spec_helper.rb
+- spec/telein/client_spec.rb
+- spec/telein/server_spec.rb
+- spec/telein/util/phone_spec.rb
+- telein-client.gemspec
+homepage: https://github.com/thiagobrandam/telein-client#readme
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      segments:
+      - 0
+      version: '0'
+      hash: 3113826130488596795
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      segments:
+      - 0
+      version: '0'
+      hash: 3113826130488596795
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: Client to access Telein API in Ruby
+test_files:
+- spec/spec_helper.rb
+- spec/telein/client_spec.rb
+- spec/telein/server_spec.rb
+- spec/telein/util/phone_spec.rb