twilio-lookups 0.0.1

data/lib/twilio-lookups.rb

@@ -0,0 +1,40 @@
+require 'net/http'
+require 'net/https'
+require 'builder'
+require 'multi_json'
+require 'cgi'
+require 'openssl'
+require 'base64'
+require 'forwardable'
+require 'jwt'
+
+require 'twilio-lookups/version' unless defined?(Twilio::VERSION)
+require 'twilio-lookups/util'
+require 'twilio-lookups/rest/utils'
+require 'twilio-lookups/rest/errors'
+require 'twilio-lookups/util/client_config'
+require 'twilio-lookups/rest/lookups_client'
+require 'twilio-lookups/rest/instance_resource'
+require 'twilio-lookups/rest/list_resource'
+require 'twilio-lookups/rest/next_gen_list_resource'
+require 'twilio-lookups/rest/lookups/phone_numbers'
+
+module TwilioLookups
+  extend SingleForwardable
+
+  def_delegators :configuration, :account_sid, :auth_token
+
+  ##
+  # Pre-configure with account SID and auth token so that you don't need to
+  # pass them to various initializers each time.
+  def self.configure(&block)
+    yield configuration
+  end
+
+  ##
+  # Returns an existing or instantiates a new configuration object.
+  def self.configuration
+    @configuration ||= Util::Configuration.new
+  end
+  private_class_method :configuration
+end

data/lib/twilio-lookups/rest/base_client.rb

@@ -0,0 +1,130 @@
+module TwilioLookups
+  module REST
+    class BaseClient
+      include TwilioLookups::Util
+      include TwilioLookups::REST::Utils
+
+      HTTP_HEADERS = {
+          'Accept' => 'application/json',
+          'Accept-Charset' => 'utf-8',
+          'User-Agent' => "twilio-ruby/#{TwilioLookups::VERSION}" \
+                        " (#{RUBY_ENGINE}/#{RUBY_PLATFORM}" \
+                        " #{RUBY_VERSION}-p#{RUBY_PATCHLEVEL})"
+      }
+
+      ##
+      # Override the default host for a REST Client (api.twilio.com)
+      def self.host(host=nil)
+        return @host unless host
+        @host = host
+      end
+
+      attr_reader :account_sid, :last_request, :last_response
+
+      def initialize(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        options[:host] ||= self.class.host
+        @config = TwilioLookups::Util::ClientConfig.new options
+
+        @account_sid = args[0] || TwilioLookups.account_sid
+        @auth_token = args[1] || TwilioLookups.auth_token
+        if @account_sid.nil? || @auth_token.nil?
+          raise ArgumentError, 'Account SID and auth token are required'
+        end
+
+        set_up_connection
+        set_up_subresources
+      end
+
+      ##
+      # Define #get, #put, #post and #delete helper methods for sending HTTP
+      # requests to TwilioLookups. You shouldn't need to use these methods directly,
+      # but they can be useful for debugging. Each method returns a hash
+      # obtained from parsing the JSON object in the response body.
+      [:get, :put, :post, :delete].each do |method|
+        method_class = Net::HTTP.const_get method.to_s.capitalize
+        define_method method do |path, *args|
+          params = twilify(args[0])
+          params = {} if params.empty?
+          # build the full path unless already given
+          path = build_full_path(path, params, method) unless args[1]
+          request = method_class.new(path, HTTP_HEADERS)
+          request.basic_auth(@account_sid, @auth_token)
+          request.form_data = params if [:post, :put].include?(method)
+          connect_and_send(request)
+        end
+      end
+
+      protected
+
+      ##
+      # Builds up full request path
+      # Needs implementation in child classes
+      def build_full_path(path, params, method)
+        raise NotImplementedError
+      end
+
+      ##
+      # Set up and cache a Net::HTTP object to use when making requests. This is
+      # a private method documented for completeness.
+      def set_up_connection # :doc:
+        connection_class = Net::HTTP::Proxy @config.proxy_addr,
+                                            @config.proxy_port, @config.proxy_user, @config.proxy_pass
+        @connection = connection_class.new @config.host, @config.port
+        set_up_ssl
+        @connection.open_timeout = @config.timeout
+        @connection.read_timeout = @config.timeout
+      end
+
+      ##
+      # Set up the ssl properties of the <tt>@connection</tt> Net::HTTP object.
+      # This is a private method documented for completeness.
+      def set_up_ssl # :doc:
+        @connection.use_ssl = @config.use_ssl
+        if @config.ssl_verify_peer
+          @connection.verify_mode = OpenSSL::SSL::VERIFY_PEER
+          @connection.ca_file = @config.ssl_ca_file
+        else
+          @connection.verify_mode = OpenSSL::SSL::VERIFY_NONE
+        end
+      end
+
+      ##
+      # Set up sub resources attributes.
+      def set_up_subresources # :doc:
+        # To be overridden
+      end
+
+      ##
+      # Send an HTTP request using the cached <tt>@connection</tt> object and
+      # return the JSON response body parsed into a hash. Also save the raw
+      # Net::HTTP::Request and Net::HTTP::Response objects as
+      # <tt>@last_request</tt> and <tt>@last_response</tt> to allow for
+      # inspection later.
+      def connect_and_send(request) # :doc:
+        @last_request = request
+        retries_left = @config.retry_limit
+        begin
+          response = @connection.request request
+          @last_response = response
+          if response.kind_of? Net::HTTPServerError
+            raise TwilioLookups::REST::ServerError
+          end
+        rescue
+          raise if request.class == Net::HTTP::Post
+          if retries_left > 0 then retries_left -= 1; retry else raise end
+        end
+        if response.body and !response.body.empty?
+          object = MultiJson.load response.body
+        elsif response.kind_of? Net::HTTPBadRequest
+          object = { message: 'Bad request', code: 400 }
+        end
+
+        if response.kind_of? Net::HTTPClientError
+          raise TwilioLookups::REST::RequestError.new object['message'], object['code']
+        end
+        object
+      end
+    end
+  end
+end

data/lib/twilio-lookups/rest/errors.rb

@@ -0,0 +1,14 @@
+module TwilioLookups
+  module REST
+    class ServerError < StandardError; end
+
+    class RequestError < StandardError
+      attr_reader :code
+
+      def initialize(message, code=nil);
+        super message
+        @code = code
+      end
+    end
+  end
+end

data/lib/twilio-lookups/rest/instance_resource.rb

@@ -0,0 +1,87 @@
+module TwilioLookups
+  module REST
+    ##
+    # A class to wrap an instance resource (like a call or application) within
+    # the Twilio API. All other instance resource classes within this library
+    # inherit from this class. You shouldn't need to instantiate this class
+    # directly. But reviewing the available methods is informative since they
+    # are rarely overridden in the inheriting class.
+    class InstanceResource
+      include Utils
+
+      ##
+      # Instantiate a new instance resource object. You must pass the +path+ of
+      # the instance (e.g. /2010-04-01/Accounts/AC123/Calls/CA456) as well as a
+      # +client+ object that responds to #get #post and #delete. This client
+      # is meant to be an instance of Twilio::REST::Client but could just as
+      # well be a mock object if you want to test the interface. The optional
+      # +params+ hash will be converted into attributes on the instantiated
+      # object.
+      def initialize(path, client, params = {})
+        @path, @client = path, client
+        set_up_properties_from params
+      end
+
+      def inspect # :nodoc:
+        "<#{self.class} @path=#{@path}>"
+      end
+
+      ##
+      # Update the properties of this instance resource using the key/value
+      # pairs in +params+. This makes an HTTP POST request to <tt>@path</tt>
+      # to handle the update. For example, to update the +VoiceUrl+ of a Twilio
+      # Application you could write:
+      #
+      #   @app.update voice_url: 'http://my.other.app.com/handle_voice'
+      #
+      # After returning, the object will contain the most recent state of the
+      # instance resource, including the newly updated properties.
+      def update(params = {})
+        raise "Can't update a resource without a REST Client" unless @client
+        set_up_properties_from(@client.post(@path, params))
+        self
+      end
+
+      ##
+      # Refresh the attributes of this instance resource object by fetching it
+      # from Twilio. Calling this makes an HTTP GET request to <tt>@path</tt>.
+      def refresh
+        raise "Can't refresh a resource without a REST Client" unless @client
+        @updated = false
+        set_up_properties_from(@client.get(@path))
+        self
+      end
+
+      ##
+      # Delete an instance resource from Twilio. This operation isn't always
+      # supported. For instance, you can't delete an SMS. Calling this method
+      # makes an HTTP DELETE request to <tt>@path</tt>.
+      def delete
+        raise "Can't delete a resource without a REST Client" unless @client
+        @client.delete @path
+      end
+
+      ##
+      # Lazily load attributes of the instance resource by waiting to fetch it
+      # until an attempt is made to access an unknown attribute.
+      def method_missing(method, *args)
+        super if @updated
+        set_up_properties_from(@client.get(@path))
+        self.send method, *args
+      end
+
+      protected
+
+      def set_up_properties_from(hash)
+        eigenclass = class << self; self; end
+        hash.each do |p,v|
+          property = detwilify p
+          unless ['client', 'updated'].include? property
+            eigenclass.send :define_method, property.to_sym, &lambda { v }
+          end
+        end
+        @updated = !hash.keys.empty?
+      end
+    end
+  end
+end

data/lib/twilio-lookups/rest/list_resource.rb

@@ -0,0 +1,100 @@
+module TwilioLookups
+  module REST
+    class ListResource
+      include Utils
+
+      def initialize(path, client)
+        custom_names = {
+          'Activities' => 'Activity',
+          'Addresses' => 'Address',
+          'Countries' => 'Country',
+          'Feedback' => 'FeedbackInstance',
+          'IpAddresses' => 'IpAddress',
+          'Media' => 'MediaInstance',
+        }
+        @path, @client = path, client
+        resource_name = self.class.name.split('::')[-1]
+        instance_name = custom_names.fetch(resource_name, resource_name.chop)
+
+        # The next line grabs the enclosing module. Necessary for resources
+        # contained in their own submodule like /SMS/Messages
+        parent_module = self.class.to_s.split('::')[-2]
+        full_module_path = if parent_module == "REST"
+          TwilioLookups::REST
+        else
+          TwilioLookups::REST.const_get parent_module
+        end
+
+        @instance_class = full_module_path.const_get instance_name
+        @list_key, @instance_id_key = detwilify(resource_name), 'sid'
+      end
+
+      def inspect # :nodoc:
+        "<#{self.class} @path=#{@path}>"
+      end
+
+      ##
+      # Grab a list of this kind of resource and return it as an array. The
+      # array includes two special methods +previous_page+ and +next_page+
+      # which will return the previous or next page or resources. By default
+      # Twilio will only return 50 resources, and the maximum number of
+      # resources you can request (using the :page_size param) is 1000.
+      #
+      # The optional +params+ hash allows you to filter the list returned. The
+      # filters for each list resource type are defined by Twilio.
+      def list(params={}, full_path=false)
+        raise "Can't get a resource list without a REST Client" unless @client
+        response = @client.get @path, params, full_path
+        resources = response[@list_key]
+        path = full_path ? @path.split('.')[0] : @path
+        resource_list = resources.map do |resource|
+          @instance_class.new "#{path}/#{resource[@instance_id_key]}", @client,
+            resource
+        end
+        # set the +previous_page+ and +next_page+ properties on the array
+        client, list_class = @client, self.class
+        resource_list.instance_eval do
+          eigenclass = class << self; self; end
+          eigenclass.send :define_method, :previous_page, &lambda {
+            if response['previous_page_uri']
+              list_class.new(response['previous_page_uri'], client).list({}, true)
+            else
+              []
+            end
+          }
+          eigenclass.send :define_method, :next_page, &lambda {
+            if response['next_page_uri']
+              list_class.new(response['next_page_uri'], client).list({}, true)
+            else
+              []
+            end
+          }
+        end
+        resource_list
+      end
+
+      ##
+      # Return an empty instance resource object with the proper path. Note that
+      # this will never raise a Twilio::REST::RequestError on 404 since no HTTP
+      # request is made. The HTTP request is made when attempting to access an
+      # attribute of the returned instance resource object, such as
+      # its #date_created or #voice_url attributes.
+      def get(sid)
+        @instance_class.new "#{@path}/#{sid}", @client
+      end
+      alias :find :get # for the ActiveRecord lovers
+
+      ##
+      # Return a newly created resource. Some +params+ may be required. Consult
+      # the Twilio REST API documentation related to the kind of resource you
+      # are attempting to create for details. Calling this method makes an HTTP
+      # POST request to <tt>@path</tt> with the given params
+      def create(params={})
+        raise "Can't create a resource without a REST Client" unless @client
+        response = @client.post @path, params
+        @instance_class.new "#{@path}/#{response[@instance_id_key]}", @client,
+          response
+      end
+    end
+  end
+end

data/lib/twilio-lookups/rest/lookups/phone_numbers.rb

@@ -0,0 +1,17 @@
+module TwilioLookups
+  module REST
+    module Lookups
+      class PhoneNumbers < TwilioLookups::REST::NextGenListResource;
+        include TwilioLookups::Util
+        include TwilioLookups::REST::Utils
+
+        def get(number, query={})
+          full_path = "#{@path}/#{URI.encode(number)}"
+          full_path << "?#{url_encode(twilify(query))}" if !query.empty?
+          @instance_class.new full_path, @client
+        end
+      end
+      class PhoneNumber < InstanceResource; end
+    end
+  end
+end

data/lib/twilio-lookups/rest/lookups_client.rb

@@ -0,0 +1,99 @@
+require 'twilio-lookups/rest/base_client'
+module TwilioLookups
+  module REST
+    class LookupsClient < BaseClient
+      API_VERSION = 'v1'
+
+      attr_reader :phone_numbers
+
+      host 'lookups.twilio.com'
+
+      ##
+      # Instantiate a new HTTP Lookups client to talk to TwilioLookups. The parameters
+      # +account_sid+, +auth_token+ and +workspace_sid are required, unless you
+      # have configured them already using the block configure syntax, and used
+      # to generate the HTTP basic auth header in each request. The +options+
+      # parameter is a hash of connection configuration options. the following
+      # keys are supported:
+      #
+      # === <tt>host: 'lookups.twilio.com'</tt>
+      #
+      # The domain to which you'd like the client to make HTTP requests. Useful
+      # for testing. Defaults to 'lookups.twilio.com'.
+      #
+      # === <tt>port: 443</tt>
+      #
+      # The port on which to connect to the above domain. Defaults to 443 and
+      # should be left that way except in testing environments.
+      #
+      # === <tt>use_ssl: true</tt>
+      #
+      # Declare whether ssl should be used for connections to the above domain.
+      # Defaults to true and should be left alone except when testing.
+      #
+      # === <tt>ssl_verify_peer: true</tt>
+      #
+      # Declare whether to verify the host's ssl cert when setting up the
+      # connection to the above domain. Defaults to true, but can be turned off
+      # to avoid ssl certificate verification failures in environments without
+      # the necessary ca certificates.
+      #
+      # === <tt>ssl_ca_file: '/path/to/ca/file'</tt>
+      #
+      # Specify the path to the certificate authority bundle you'd like to use
+      # to verify TwilioLookups's SSL certificate on each request. If not specified, a
+      # certificate bundle extraced from Firefox is packaged with the gem and
+      # used by default.
+      #
+      # === <tt>timeout: 30</tt>
+      #
+      # Set the time in seconds to wait before timing out the HTTP request.
+      # Defaults to 30 seconds. If you aren't fetching giant pages of call or
+      # SMS logs you can safely decrease this to something like 3 seconds or
+      # lower. In paricular if you are sending SMS you can set this to 1 second
+      # or less and swallow the exception if you don't care about the response.
+      #
+      # === <tt>proxy_addr: 'proxy.host.domain'</tt>
+      #
+      # The domain of a proxy through which you'd like the client to make HTTP
+      # requests. Defaults to nil.
+      #
+      # === <tt>proxy_port: 3128</tt>
+      #
+      # The port on which to connect to the above proxy. Defaults to nil.
+      #
+      # === <tt>proxy_user: 'username'</tt>
+      #
+      # The user name to use for authentication with the proxy. Defaults to nil.
+      #
+      # === <tt>proxy_pass: 'password'</tt>
+      #
+      # The password to use for authentication with the proxy. Defaults to nil.
+      #
+      # === <tt>retry_limit: 1</tt>
+      #
+      # The number of times to retry a request that has failed before throwing
+      # an exception. Defaults to one.
+      def inspect # :nodoc:
+        "<TwilioLookups::REST::LookupsClient @account_sid=#{@account_sid}>"
+      end
+
+      protected
+
+      ##
+      # Set up +phone_numbers+ attribute.
+      def set_up_subresources # :doc:
+        @phone_numbers = TwilioLookups::REST::Lookups::PhoneNumbers.new "/#{API_VERSION}/PhoneNumbers", self
+      end
+
+      ##
+      # Builds up full request path
+      def build_full_path(path, params, method)
+        path = path.dup
+        path << "?#{url_encode(params)}" if method == :get && !params.empty?
+        path
+      end
+
+    end
+  end
+end