phaxio 0.4.0 → 2.1.0.pre

data/lib/phaxio/resources/phone_number.rb

@@ -0,0 +1,112 @@
+module Phaxio
+  module Resources
+    # Provides functionality for viewing and managing phone numbers.
+    class PhoneNumber < Resource
+      PHONE_NUMBERS_PATH = 'phone_numbers'.freeze
+      private_constant :PHONE_NUMBERS_PATH
+
+      # @return [String] The phone number itself, in E.164 format.
+      # @!attribute phone_number
+
+      # @return [String] The city associated with the phone number.
+      # @!attribute city
+
+      # @return [String] The state associated with the phone number.
+      # @!attribute state
+
+      # @return [String] The country associated with the phone number.
+      # @!attribute country
+
+      # @return [Integer] The cost of the phone number in cents.
+      # @!attribute cost
+
+      # @return [String] The callback URL associated with the phone number.
+      # @!attribute callback_url
+
+      has_normal_attributes %w(phone_number city state country cost callback_url)
+
+      # @return [Time] The time at which the phone number was provisioned.
+      # @!attribute provisioned_at
+
+      # @return [Time] The last time the phone number was billed.
+      # @!attribute last_billed_at
+
+      has_time_attributes %w(provisioned_at last_billed_at)
+
+      private
+
+      class << self
+        # Provision a new phone number.
+        # @param params [Hash]
+        #   A hash of parameters to send to Phaxio:
+        #   - *country_code* [Integer] - The country code (E.164) of the number you'd like to provision.
+        #   - *area_code* [Integer] - The area code of the number you'd like to provision.
+        #   - *callback_url* [String] - A callback URL that we'll post to when a fax is received by this number. This will override the global receive callback URL, if you have one specified.
+        # @return [Phaxio::Resources::PhoneNumber] The newly provisioned number.
+        # @raise [Phaxio::Error::PhaxioError]
+        # @see https://www.phaxio.com/docs/api/v2/phone_numbers/provision
+        def create params = {}
+          response = Client.request :post, phone_numbers_endpoint, params
+          response_record response
+        end
+        alias :provision :create
+
+        # Get information about a specific phone number.
+        # @param phone_number [String]
+        #   The phone number itself, in E.164 format, which you want to get information about.
+        # @param params [Hash]
+        #   A hash of parameters to send to Phaxio. This action has no unique parameters.
+        # @return [Phaxio::Resources::PhoneNumber] The requested number.
+        # @raise [Phaxio::Error::PhaxioError]
+        # @see https://www.phaxio.com/docs/api/v2/phone_numbers/get_number
+        def get phone_number, params = {}
+          response = Client.request :get, phone_number_endpoint(phone_number), params
+          response_record response
+        end
+        alias :find :get
+        alias :retrieve :get
+
+        # @macro paging
+        # Get a list of phone numbers that you currently own on Phaxio.
+        # @param params [Hash]
+        #   A hash of parameters to send to Phaxio.
+        #   - *country_code* [Integer] - An E.164 country code that you'd like to filter by.
+        #   - *area_code* [Integer] - An area code that you'd like to filter by. If an area code is
+        #     specified, then *country_code* is required.
+        # @return [Phaxio::Resource::Collection<Phaxio::Resources::PhoneNumber>]
+        #   A collection of phone numbers.
+        # @raise [Phaxio::Error::PhaxioError]
+        # @see https://www.phaxio.com/docs/api/v2/phone_numbers/list
+        def list params = {}
+          response = Client.request :get, phone_numbers_endpoint, params
+          response_collection response
+        end
+
+        # Release a phone number that you no longer need. Once a phone number is released you will
+        # no longer be charged for it.
+        # @param phone_number [String]
+        #   The phone number itself, in E.164 format, which you want to release.
+        # @param params [Hash]
+        #   A hash of parameters to send to Phaxio. This action has no unique parameters.
+        # @return true
+        # @raise [Phaxio::Error::PhaxioError]
+        # @see https://www.phaxio.com/docs/api/v2/phone_numbers/release
+        def delete phone_number, params = {}
+          Client.request :delete, phone_number_endpoint(phone_number), params
+          true
+        end
+        alias :release :delete
+
+        private
+
+        def phone_numbers_endpoint
+          PHONE_NUMBERS_PATH
+        end
+
+        def phone_number_endpoint phone_number
+          "#{phone_numbers_endpoint}/#{phone_number}"
+        end
+      end
+    end
+  end
+end

data/lib/phaxio/resources/public.rb

@@ -0,0 +1,8 @@
+module Phaxio
+  module Resources
+    module Public
+    end
+  end
+end
+
+Dir[File.expand_path(File.join('..', 'public', '*.rb'), __FILE__)].each { |file| require file }

data/lib/phaxio/resources/public/area_code.rb

@@ -0,0 +1,64 @@
+module Phaxio
+  module Resources
+    module Public
+      # Information about area codes for provisioning numbers.
+      #
+      # @see Phaxio::Resources::PhoneNumber.list_available_area_codes
+      class AreaCode < Resource
+        AVAILABLE_AREA_CODES_PATH = 'public/area_codes'.freeze
+        private_constant :AVAILABLE_AREA_CODES_PATH
+
+        # @return [Integer] The country code associated with this area code.
+        # @!attribute country_code
+
+        # @return [Integer] The actual area code.
+        # @!attribute area_code
+
+        # @return [String] The city associated with this area code.
+        # @!attribute city
+
+        # @return [String] The state associated with this area code.
+        # @!attribute state
+
+        # @return [String] The country associated with this area code.
+        # @!attribute country
+
+        # @return [true | false] Indicates whether this area code is toll free.
+        # @!attribute toll_free
+
+        has_normal_attributes %w[country_code area_code city state country toll_free]
+
+        class << self
+          # @macro paging
+          # Displays a list of area codes available for purchasing Phaxio numbers. This operation
+          # requires no authentication and can be used without passing an API key.
+          # @param params [Hash]
+          #   A hash of parameters to send to Phaxio.
+          #   - *toll_free* [true|false] - If set to *true*, only toll free area codes will be
+          #     returned. If specified and set to *false*, only non-toll free area codes will be
+          #     returned.
+          #   - *country_code* [Integer] - An E.164 country code you'd like to filter by.
+          #   - *country* [String] - A two character country abbreviation (ISO 3166; e.g. "US" or
+          #     "CA") you'd like to filter by.
+          #   - *state* [String] - A two character state or province abbreviation (ISO 3166; e.g.
+          #     "IL" or "YT") you'd like to filter by. When using this parameter, *country_code* or
+          #     *country* must also be provided.
+          # @return [Phaxio::Resource::Collection<Phaxio::Resources::AreaCode>] A collection of
+          #   AreaCode objects.
+          # @raise [Phaxio::Error::PhaxioError]
+          # @see https://www.phaxio.com/docs/api/v2/public/list_area_codes
+          def list params = {}
+            response = Client.request :get, available_area_codes_endpoint, params
+            AreaCode.response_collection response
+          end
+
+          private
+
+          def available_area_codes_endpoint
+            AVAILABLE_AREA_CODES_PATH
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phaxio/resources/public/country.rb

@@ -0,0 +1,54 @@
+module Phaxio
+  module Resources
+    module Public
+      class Country < Resource
+        SUPPORTED_COUNTRIES_PATH = 'public/countries'.freeze
+        private_constant :SUPPORTED_COUNTRIES_PATH
+
+        # @return [String] the name of the country.
+        # @!attribute name
+
+        # @return [String] the alpha2 representation of the country.
+        # @!attribute alpha2
+
+        # @return [Integer] the E.164 country code for the country.
+        # @!attribute country_code
+
+        # @return [Integer] the price per page for the country, in cents.
+        # @!attribute price_per_page
+
+        # @return [String] the level of send support provided for this country.
+        # @!attribute send_support
+
+        # @return [String] the level of receive support provided for this country.
+        # @!attribute receive_support
+
+        has_normal_attributes %w[
+          name alpha2 country_code price_per_page send_support receive_support
+        ]
+
+        class << self
+          # @macro paging
+          # Get a list of supported countries for sending faxes.
+          # @param params [Hash]
+          #   A hash of parameters to send to Phaxio. This action has no unique
+          #   parameters.
+          # @return [Phaxio::Resource::Collection<Phaxio::Resources::Country>]
+          #   A collection of supported countries.
+          # @raise Phaxio::Error::PhaxioError
+          # @see https://www.phaxio.com/docs/api/v2/public/list_countries
+          def list params = {}
+            response = Client.request :get, supported_countries_endpoint, params
+            Country.response_collection response
+          end
+
+          private
+
+          def supported_countries_endpoint
+            SUPPORTED_COUNTRIES_PATH
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phaxio/version.rb

@@ -1,3 +1,3 @@
 module Phaxio
-  VERSION = "0.4.0"
+  VERSION = "2.1.0.pre"
 end

data/phaxio.gemspec

@@ -2,11 +2,11 @@
 require File.expand_path('../lib/phaxio/version', __FILE__)
 
 Gem::Specification.new do |gem|
-  gem.authors       = ["Sean Behan", "Brett Chalupa"]
-  gem.email         = ["inbox@seanbehan.com", "brettchalupa@gmail.com"]
-  gem.description   = %q{A Ruby Gem for interacting with Phaxio's JSON API. Currently, not all of the Phaxio API calls are supported. The essentials are in place and more will be coming with future versions of this gem.}
-  gem.summary       = %q{A Ruby Gem for interacting with Phaxio's JSON API}
-  gem.homepage      = "http://www.gristmill.io/posts/17-introducing-the-phaxio-gem-an-easy-way-to-use-phaxio-with-ruby"
+  gem.authors       = ["Julien Negrotto"]
+  gem.email         = ["julien@phaxio.com"]
+  gem.description   = %q{Official ruby gem for interacting with Phaxio's API.}
+  gem.summary       = %q{Official ruby gem for interacting with Phaxio's API.}
+  gem.homepage      = "https://github.com/phaxio/phaxio-ruby"
 
   gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   gem.files         = `git ls-files`.split("\n")
@@ -14,8 +14,10 @@ Gem::Specification.new do |gem|
   gem.name          = "phaxio"
   gem.require_paths = ["lib"]
   gem.version       = Phaxio::VERSION
+  gem.licenses      = ['MIT']
 
-  gem.add_runtime_dependency      "httmultiparty", "~> 0.3.8"
-  gem.add_development_dependency  "fakeweb",       "~> 1.3.0"
-  gem.add_development_dependency  "rake",          "~> 0.9.2.2"
+  gem.required_ruby_version = '>= 2.0'
+  gem.add_dependency 'faraday', '>= 0.10', '< 2.0'
+  gem.add_dependency 'mime-types', '~> 3.0'
+  gem.add_dependency 'activesupport'
 end

data/spec/client_spec.rb

@@ -0,0 +1,164 @@
+require 'spec_helper'
+
+RSpec.describe Phaxio::Client do
+  subject(:client) { Phaxio::Client }
+  let(:test_connection) { instance_double Faraday::Connection }
+
+  before do
+    allow(client).to receive(:conn) { test_connection }
+  end
+
+  def test_response status_code, message: 'This is a test.'
+    success = (200..299).include? status_code
+    instance_double(
+      Faraday::Response,
+      status: status_code,
+      success?: success,
+      headers: {content_type: 'application/json'},
+      body: %Q({"success": #{success}, "message": "#{message}", "data": {"foo": "bar"}})
+    )
+  end
+
+  describe 'making a request' do
+    it 'sends the request to Phaxio' do
+      endpoint = 'public/countries/'
+      params = {page: 1, per_page: 10}
+      expect(test_connection).to receive(:get) do |request_endpoint, request_params|
+        expect(request_endpoint).to eq(endpoint)
+        expect(request_params[:page]).to eq(params[:page])
+        expect(request_params[:per_page]).to eq(params[:per_page])
+        test_response 200
+      end
+      client.request :get, endpoint, params
+    end
+
+    it 'handles a single file param' do
+      file_path = File.expand_path File.join('..', 'support', 'files', 'test.pdf'), __FILE__
+      params = {to: '+12258888888', file: File.open(file_path)}
+      expect(test_connection).to receive(:post) do |request_endpoint, request_params|
+        expect(request_params[:file]).to be_a(Faraday::UploadIO)
+        expect(request_params[:file].original_filename).to eq(File.basename(file_path))
+        test_response 200
+      end
+
+      client.request :post, 'faxes', params
+    end
+
+    it 'handles multiple file params' do
+      file_names = ['test.pdf', 'test.txt']
+      file_paths = file_names.map do |file_name|
+        File.expand_path File.join('..', 'support', 'files', file_name), __FILE__
+      end
+      params = {to: '+12258888888', file: file_paths.map { |file_path| File.open(file_path) }}
+
+      expect(test_connection).to receive(:post) do |request_endpoint, request_params|
+        expect(request_params[:file]).to be_a(Array)
+        correct_file_params = request_params[:file].all? do |file_param|
+          file_param.is_a? Faraday::UploadIO
+        end
+        expect(correct_file_params).to eq(true)
+        expect(request_params[:file].map(&:original_filename)).to eq(file_names)
+        test_response 200
+      end
+
+      client.request :post, 'faxes', params
+    end
+
+    it 'uses the configured API key and secret by default' do
+      expect(test_connection).to receive(:get) do |_endpoint, _request_params, request_headers|
+        auth_header = "Basic #{Base64.strict_encode64("#{Phaxio.api_key}:#{Phaxio.api_secret}")}"
+        expect(request_headers['Authorization']).to eq(auth_header)
+        test_response 200
+      end
+      client.request :get, 'test'
+    end
+
+    it 'uses the api key specified in the params hash' do
+      custom_api_key = 'custom-api-key'
+      custom_api_secret = 'custom-api-secret'
+      expect(test_connection).to receive(:get) do |_endpoint, _request_params, request_headers|
+        auth_header = "Basic #{Base64.strict_encode64('custom-api-key:custom-api-secret')}"
+        expect(request_headers['Authorization']).to eq(auth_header)
+        test_response 200
+      end
+      client.request :get, 'test', api_key: custom_api_key, api_secret: custom_api_secret
+    end
+
+    it 'parses the response JSON and returns the data if the response indicates success' do
+      expect(test_connection).to receive(:get) { test_response 200 }
+      result = client.request :get, 'test'
+      expect(result).to eq({'foo' => 'bar'})
+    end
+
+    it 'raises an authentication error if the response status is 401' do
+      expect(test_connection).to receive(:get) { test_response 401 }
+      expect {
+        client.request :get, 'test'
+      }.to raise_error(Phaxio::Error::AuthenticationError, '401: This is a test.')
+    end
+
+    it 'raises a not found error if the response status is 404' do
+      expect(test_connection).to receive(:get) { test_response 404 }
+      expect do
+        client.request :get, 'test'
+      end.to raise_error(Phaxio::Error::NotFoundError, '404: This is a test.')
+    end
+
+    it 'raises an invalid request error if the response status is 422' do
+      expect(test_connection).to receive(:get) { test_response 422 }
+      expect {
+        client.request :get, 'test'
+      }.to raise_error(Phaxio::Error::InvalidRequestError, '422: This is a test.')
+    end
+
+    it 'raises a rate limit error if the response status is 429' do
+      expect(test_connection).to receive(:get) { test_response 429 }
+      expect {
+        client.request :get, 'test'
+      }.to raise_error(Phaxio::Error::RateLimitExceededError, '429: This is a test.')
+    end
+
+    it 'raises a general error for if the response status is 5XX' do
+      expect(test_connection).to receive(:get) { test_response 500 }
+      expect {
+        client.request :get, 'test'
+      }.to raise_error(Phaxio::Error::GeneralError, '500: This is a test.')
+    end
+
+    it 'raises a general error if the response status is some other value' do
+      expect(test_connection).to receive(:get) { test_response 418 }
+      expect {
+        client.request :get, 'test'
+      }.to raise_error(Phaxio::Error::GeneralError, '418: This is a test.')
+    end
+
+    it 'raises an API connection error if a networking issue occurs' do
+      expect(test_connection).to receive(:get) { raise Faraday::ConnectionFailed, 'This is a test.' }
+      expect {
+        client.request :get, 'test'
+      }.to raise_error(Phaxio::Error::ApiConnectionError, 'Error communicating with Phaxio: This is a test.')
+    end
+
+    it 'allows unknown errors to bubble up' do
+      expect(test_connection).to receive(:get) { raise RuntimeError, 'This is a test.' }
+      expect {
+        client.request :get, 'test'
+      }.to raise_error(RuntimeError, 'This is a test.')
+    end
+
+    it 'raises a general error if the status indicates success but the body indicates failure' do
+      expect(test_connection).to receive(:get) do
+        instance_double(
+          Faraday::Response,
+          status: 200,
+          success?: true,
+          headers: {content_type: 'application/json'},
+          body: '{"success": false, "message": "Something bad happened.", "data": {"foo": "bar"}}'
+        )
+      end
+      expect {
+        client.request :get, 'test'
+      }.to raise_error(Phaxio::Error::GeneralError, "Something bad happened.")
+    end
+  end
+end

data/spec/helpers/mime_type_helper_spec.rb

@@ -0,0 +1,11 @@
+require 'spec_helper'
+
+describe Phaxio::MimeTypeHelper do
+  it 'gets the mimetype for a filename' do
+    expect(subject.mimetype_for_file('test.pdf')).to eq('application/pdf')
+  end
+
+  it 'gets the extension for a mimetype' do
+    expect(subject.extension_for_mimetype('application/pdf')).to eq('pdf')
+  end
+end