phaxio 0.5.0 → 2.0.0

data/lib/phaxio/resources/fax_recipient.rb

@@ -0,0 +1,41 @@
+module Phaxio
+  module Resources
+    class FaxRecipient < Resource
+      # @return [String] The phone number of the recipient in E.164 format.
+      # @!attribute phone_number
+
+      # @return [String] The status of the recipient.
+      # @!attribute status
+
+      # @return [Integer] The number of retries for this recipient.
+      # @!attribute retry_count
+
+      # @return [Integer] The bitrate in bits/second that the fax was transmitted at.
+      # @!attribute bitrate
+
+      # @return [Integer]
+      #   The horizontal resolution that the fax was transmitted at in pixels per meter.
+      # @!attribute resolution
+
+      # @return [String]
+      #   One of the Phaxio Error types. Will give you a general idea of what went wrong for this
+      #   recipient.
+      # @!attribute error_type
+
+      # @return [String] A more detailed description of what went wrong for this receipient.
+      # @!attribute error_message
+
+      # @return [Integer] A numeric error code that corresponds to the error message, if any.
+      # @!attribute error_id
+
+      has_normal_attributes %w[
+        phone_number status retry_count bitrate resolution error_type error_message error_id
+      ]
+
+      # @return [Time] The time the job was completed for this recipient.
+      # @!attribute completed_at
+
+      has_time_attributes %w[completed_at]
+    end
+  end
+end

data/lib/phaxio/resources/phax_code.rb

@@ -0,0 +1,89 @@
+module Phaxio
+  module Resources
+    # Provides functionality for viewing and managing PhaxCodes.
+    class PhaxCode < Resource
+      PHAX_CODES_PATH = 'phax_codes'.freeze
+      DEFAULT_PHAX_CODE_PATH = 'phax_code'.freeze
+      private_constant :PHAX_CODES_PATH, :DEFAULT_PHAX_CODE_PATH
+
+      # @return [String] The identifier for the PhaxCode.
+      # @!attribute identifier
+
+      # @return [String] The metadata associated with the PhaxCode.
+      # @!attribute metadata
+
+      has_normal_attributes %w[identifier metadata]
+
+      # @return [Time] The time that the PhaxCode was created.
+      # @!attribute created_at
+
+      has_time_attributes %w[created_at]
+
+      class << self
+        # Create a PhaxCode.
+        # @param params [Hash]
+        #   A hash of parameters to send to Phaxio.
+        #   - *metadata* [String] - Metadata to be associated with the PhaxCode.
+        #   - *type* [String] - If set to "png", this method will return a PNG
+        #     file instead of a PhaxCode object.
+        # @return [Phaxio::Resources::PhaxCode | File] The created PhaxCode
+        # @raise [Phaxio::Error::PhaxioError]
+        # @see https://www.phaxio.com/docs/api/v2/phaxcodes/create_phax_code
+        def create params = {}
+          endpoint = case (params[:type] || params['type']).to_s
+            when 'png' then phax_codes_endpoint_png
+            else phax_codes_endpoint
+          end
+          result = Client.request :post, endpoint, params
+          return result if result.is_a? File
+          response_record result
+        end
+
+        # Retrieve a PhaxCode.
+        # @param params [Hash]
+        #   A hash of parameters to send to Phaxio.
+        #   - *identifier* [String] - The identifier for the PhaxCode you want to get. If blank, the
+        #     default PhaxCode will be returned.
+        #   - *type* [String] - If set to "png", this method will return a PNG file instead of a
+        #     PhaxCode object.
+        # @return [Phaxio::Resources::PhaxCode | File]
+        # @raise [Phaxio::Error::PhaxioError]
+        # @see https://www.phaxio.com/docs/api/v2/phaxcodes/retrieve_phax_code
+        def get params = {}
+          identifier = params[:identifier] || params['identifier']
+          endpoint = case (identifier)
+            when nil then default_phax_code_path
+            else phax_code_endpoint(identifier)
+          end
+          endpoint = case (params[:type] || params['type']).to_s
+            when 'png' then "#{endpoint}.png"
+            else endpoint
+          end
+          result = Client.request :get, endpoint, {}
+          return result if result.is_a? File
+          response_record result
+        end
+        alias :find :get
+        alias :retrieve :get
+
+        private
+
+        def phax_codes_endpoint
+          PHAX_CODES_PATH
+        end
+
+        def phax_codes_endpoint_png
+          "#{phax_codes_endpoint}.png"
+        end
+
+        def phax_code_endpoint(identifier)
+          "#{phax_codes_endpoint}/#{identifier}"
+        end
+
+        def default_phax_code_path
+          DEFAULT_PHAX_CODE_PATH
+        end
+      end
+    end
+  end
+end

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.5.0"
+  VERSION = "2.0.0"
 end

data/phaxio.gemspec

@@ -2,11 +2,11 @@
 require File.expand_path('../lib/phaxio/version', __FILE__)
 
 Gem::Specification.new do |gem|
-  gem.authors       = ["Josh Nankin"]
-  gem.email         = ["support@phaxio.com"]
-  gem.description   = %q{Ruby wrapper for the Phaxio API}
-  gem.summary       = %q{Ruby wrapper for the Phaxio API}
-  gem.homepage      = "http://github.com/phaxio/phaxio-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")
@@ -15,11 +15,8 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
   gem.version       = Phaxio::VERSION
 
-  gem.add_runtime_dependency "httmultiparty"
-
-  gem.add_development_dependency 'bundler'
-  gem.add_development_dependency 'fakeweb', '~> 1.3'
-  gem.add_development_dependency 'rake', '~> 10'
-  gem.add_development_dependency 'minitest', '~> 5'
-  gem.add_development_dependency 'mocha', '~> 1.1'
+  gem.required_ruby_version = '>= 2.0'
+  gem.add_dependency 'faraday', '~> 0.10'
+  gem.add_dependency 'mime-types', '~> 3.0'
+  gem.add_dependency 'activesupport'
 end

data/spec/client_spec.rb

@@ -0,0 +1,132 @@
+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 'uses the configured API key and secret by default' do
+      expect(test_connection).to receive(:get) do |_endpoint, request_params|
+        expect(request_params[:api_key]).to eq(Phaxio.api_key)
+        expect(request_params[:api_secret]).to eq(Phaxio.api_secret)
+        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|
+        expect(request_params[:api_key]).to eq(custom_api_key)
+        expect(request_params[:api_secret]).to eq(custom_api_secret)
+        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