phaxio 2.1.0.pre → 2.1.1

data/lib/phaxio/resources/phone_number.rb

@@ -33,6 +33,32 @@ module Phaxio
 
       has_time_attributes %w(provisioned_at last_billed_at)
 
+      # A reference to a phone number, returned by some actions.
+      class Reference
+        # @return [String]
+        #   The phone number in E.164 format.
+        attr_accessor :phone_number
+
+        def to_s
+          phone_number
+        end
+
+        # Gets the referenced phone number.
+        # @return [Phaxio::Resources::PhoneNumber]
+        #   The referenced phone number.
+        def get
+          PhoneNumber.get self
+        end
+        alias :retrieve :get
+        alias :find :get
+
+        private
+
+        def initialize phone_number
+          self.phone_number = phone_number
+        end
+      end
+
       private
 
       class << self
@@ -44,7 +70,7 @@ module Phaxio
         #   - *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
+        # @see https://www.phaxio.com/docs/api/v2.1/phone_numbers/provision
         def create params = {}
           response = Client.request :post, phone_numbers_endpoint, params
           response_record response
@@ -58,9 +84,9 @@ module Phaxio
         #   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
+        # @see https://www.phaxio.com/docs/api/v2.1/phone_numbers/get_number
         def get phone_number, params = {}
-          response = Client.request :get, phone_number_endpoint(phone_number), params
+          response = Client.request :get, phone_number_endpoint(phone_number.to_s), params
           response_record response
         end
         alias :find :get
@@ -76,7 +102,7 @@ module Phaxio
         # @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
+        # @see https://www.phaxio.com/docs/api/v2.1/phone_numbers/list
         def list params = {}
           response = Client.request :get, phone_numbers_endpoint, params
           response_collection response
@@ -90,7 +116,7 @@ module Phaxio
         #   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
+        # @see https://www.phaxio.com/docs/api/v2.1/phone_numbers/release
         def delete phone_number, params = {}
           Client.request :delete, phone_number_endpoint(phone_number), params
           true

data/lib/phaxio/resources/port_number.rb

@@ -0,0 +1,42 @@
+module Phaxio
+  module Resources
+    # Provides functionality for viewing port numbers.
+    class PortNumber < Resource
+      PORT_NUMBERS_PATH = 'port_numbers'.freeze
+      private_constant :PORT_NUMBERS_PATH
+
+      # @return [Integer] the ID associated with this number.
+      # @!attribute id
+
+      # @return [String] the E.164 number.
+      # @!attribute port_number
+
+      # @return [String] the status of this number.
+      # @!attribute status
+      
+      has_normal_attributes %w(id port_number status)
+
+      class << self
+        # Get port number info.
+        # @param id [Integer] The ID of the number to retrieve.
+        # @param params [Hash]
+        #   A hash of parameters to send to Phaxio. This action takes no unique parameters.
+        # @return [Phaxio::Resource::PortNumber]
+        # @raise [Phaxio::Error::PhaxioError]
+        # @see https://www.phaxio.com/docs/api/v2/port_numbers/get_port_number
+        def get id, params = {}
+          response = Client.request :get, port_number_endpoint(id.to_i), params
+          response_record response
+        end
+        alias :retrieve :get
+        alias :find :get
+
+        private
+
+        def port_number_endpoint id
+          "#{PORT_NUMBERS_PATH}/#{id}"
+        end
+      end
+    end
+  end
+end

data/lib/phaxio/resources/port_number_note.rb

@@ -0,0 +1,51 @@
+module Phaxio
+  module Resources
+    # Provides functionality for viewing port number notes.
+    class PortNumberNote < Resource
+      PORT_NUMBERS_PATH = 'port_numbers'.freeze
+      private_constant :PORT_NUMBERS_PATH
+      NOTES_PATH = 'notes'.freeze
+      private_constant :NOTES_PATH
+
+      # @return [Integer] the ID associated with this note.
+      # @!attribute id
+
+      # @return [String] the author of this note.
+      # @!attribute author
+
+      # @return [String] the content of the note
+      # @!attribute note
+
+      has_normal_attributes %w[id note author]
+
+      # @return [Time] the time this note was created.
+      # @!attribute created_at
+      
+      # @return [Time] the time this note was updated.
+      # @!attribute updated_at
+
+      has_time_attributes %w[created_at updated_at]
+
+      class << self
+        # List notes for a port number.
+        # @param port_number_id [Integer]
+        #   The ID of the port number to list notes for.
+        # @param params [Hash]
+        #   Any parameters to send to Phaxio. This action takes no unique parameters.
+        # @return [Phaxio::Resource::Collection<Phaxio::Resources::PortNumberNote>]
+        # @raise [Phaxio::Error::PhaxioError]
+        # @see https://www.phaxio.com/docs/api/v2/port_number_notes/list_notes
+        def list port_number_id, params = {}
+          response = Client.request :get, port_number_notes_endpoint(port_number_id.to_i), params
+          response_collection response
+        end
+
+        private
+
+        def port_number_notes_endpoint port_number_id
+          "#{PORT_NUMBERS_PATH}/#{port_number_id}/#{NOTES_PATH}"
+        end
+      end
+    end
+  end
+end

data/lib/phaxio/resources/port_order.rb

@@ -0,0 +1,172 @@
+module Phaxio
+  module Resources
+    # Provides functionality for viewing and managing port orders.
+    class PortOrder < Resource
+      PORT_ORDERS_PATH = 'port_orders'.freeze
+      private_constant :PORT_ORDERS_PATH
+
+      # @return [Integer] the ID associated with this order.
+      # @!attribute id
+
+      # @return [String] the status of this order.
+      # @!attribute status
+
+      # @return [String] the E.164 contact number.
+      # @!attribute contact_number
+
+      # @return [String] The email address for the order.
+      # @!attribute contact_email
+
+      # @return [String] The identifier for the account associated with the numbers.
+      # @!attribute account_identifier
+
+      # @return [String] Type of numbers to be ported. Either "business" or "residential".
+      # @!attribute port_type
+
+      # @return [String] The PIN or password needed to port out the numbers.
+      # @!attribute port_out_pin
+
+      # @return [String] the name associated with the account.
+      # @!attribute name_on_account
+
+      # @return [String] the name of the business.
+      # @!attribute name_of_business
+
+      # @return [String] the provider name.
+      # @!attribute provider_name
+
+      # @return [String] the E.164 billing number.
+      # @!attribute billing_number
+
+      # @return [String] the first billing address line.
+      # @!attribute billing_address1
+
+      # @return [String] the second billing address line.
+      # @!attribute billing_address2
+
+      # @return [String] the billing address city.
+      # @!attribute billing_city
+
+      # @return [String] the billing address state.
+      # @!attribute billing_state
+
+      # @return [String] the billing address zip.
+      # @!attribute billing_zip
+
+      # @return [String] the electronic signature used to sign the order.
+      # @!attribute esig
+
+      # @return [true | false]
+      #   whether or not a bill will be provided. (only present on new orders)
+      # @!attribute has_bill
+
+      # @return [true | false]
+      #   whether or not the legal agreement is accepted. (only present on new orders)
+      # @!attribute legal_agreement
+
+      has_normal_attributes %w[
+        id contact_number contact_email name_on_account name_of_business provider_name
+        billing_number billing_address1 billing_address2 account_identifier
+        billing_city billing_state billing_zip esig legal_agreement port_type port_out_pin
+        status
+      ]
+
+      # @return [Time] the time the order was created.
+      # @!attribute created_at
+
+      # @return [Time] the time the order was updated.
+      # @!attribute updated_at
+
+      # @return [Time] the time the bill for the order was received.
+      # @!attribute bill_received_at
+
+      # @return [Time] the time the order was requested for.
+      # @!attribute requested_for
+
+      # @return [Time] the time the order was completed.
+      # @!attribute completed_at
+
+      has_time_attributes %w[
+        created_at updated_at bill_received_at requested_for completed_at
+      ]
+
+      # @return [Phaxio::Resource::Collection<Phaxio::Resources::PortNumber>]
+      #   a collection of port numbers associated with the order
+      # @!attribute port_numbers
+
+      has_collection_attributes({port_numbers: PortNumber})
+
+      class << self
+        # @macro paging
+        # List port orders in date range.
+        # @param params [Hash]
+        #   Any parameters to send to Phaxio.
+        #   - *created_before* [String] - RFC 3339 timestamp representing the end of the range.
+        #   - *created_after* [String] - RFC 3339 timestamp representing the beginning of the range.
+        # @return [Phaxio::Resource::Collection<Phaxio::Resources::PortOrder>]
+        #   The collection of port orders matching your request.
+        # @raise [Phaxio::Error::PhaxioError
+        # @see https://www.phaxio.com/docs/api/v2/port_orders/list_port_orders
+        def list params = {}
+          response = Client.request :get, port_orders_endpoint, params
+          response_collection response
+        end
+
+        # Create a port order.
+        # @param params [Hash]
+        #   Any parameters to send to Phaxio.
+        #   - *port_numbers* [Array<String>] - Numbers to port.
+        #   - *contact_number* [String] - Number to contact about the port.
+        #   - *contact_email* [String] - The email address for the order.
+        #   - *account_identifier* [String] - The identifier for the account associated with the numbers.
+        #   - *port_type* [String] - Type of numbers to be ported. Either "business" or "residential".
+        #   - *port_out_pin* [String] - The PIN or password needed to port out the numbers.
+        #   - *name_on_account* [String] - Name on the account for the port.
+        #   - *name_of_business* [String] - Name of business associated with the port.
+        #   - *provider_name* [String] - Name of provider for the port.
+        #   - *esig* [String] - Electronic signature used to sign the order.
+        #   - *legal_agreement* [true | false] - Indicates acceptance of the legal agreement.
+        #   - *has_bill* [true | false] - Indicates whether or not a bill will be provided.  If true, billing number
+        #     and address fields are not needed.
+        #   - *billing_number* [String] - Billing number.
+        #   - *billing_address1* [String] - Billing address line 1
+        #   - *billing_address2* [String] - Billing address line 2
+        #   - *billing_city* [String] - Billing address city.
+        #   - *billing_state* [String] - Billing address state.
+        #   - *billing_zip* [String] - Billing address zip.
+        # @return [Phaxio::Resources::PortOrder]
+        # @raise [Phaxio::Error::PhaxioError]
+        # @see https://www.phaxio.com/docs/api/v2/port_orders/create_port_order
+        def create params = {}
+          response = Client.request :post, port_orders_endpoint, params
+          response_record response
+        end
+
+        # Get port order info.
+        # @param id [Integer]
+        #   The ID of the order to retrieve.
+        # @param params [Hash]
+        #   A hash of parameters to send to Phaxio. This action takes no unique parameters.
+        # @return [Phaxio::Resource::PortOrder]
+        # @raise [Phaxio::Error::PhaxioError]
+        # @see https://www.phaxio.com/docs/api/v2/port_orders/get_port_order
+        def get id, params = {}
+          response = Client.request :get, port_order_endpoint(id.to_i), params
+          response_record response
+        end
+        alias :retrieve :get
+        alias :find :get
+
+        private
+
+        def port_orders_endpoint
+          PORT_ORDERS_PATH
+        end
+
+        def port_order_endpoint id
+          "#{PORT_ORDERS_PATH}/#{id}"
+        end
+      end
+    end
+  end
+end

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

@@ -46,7 +46,7 @@ module Phaxio
           # @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
+          # @see https://www.phaxio.com/docs/api/v2.1/public/list_area_codes
           def list params = {}
             response = Client.request :get, available_area_codes_endpoint, params
             AreaCode.response_collection response

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

@@ -36,7 +36,7 @@ module Phaxio
           # @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
+          # @see https://www.phaxio.com/docs/api/v2.1/public/list_countries
           def list params = {}
             response = Client.request :get, supported_countries_endpoint, params
             Country.response_collection response

data/lib/phaxio/resources/webhook.rb

@@ -0,0 +1,65 @@
+module Phaxio
+  module Resources
+    # Provides utilities for working with webhooks.
+    # @see https://www.phaxio.com/docs/api/v2.1/faxes/send_webhook
+    # @see https://www.phaxio.com/docs/api/v2.1/faxes/receive_webhooks
+    class Webhook
+      DIGEST = OpenSSL::Digest.new('sha1')
+      private_constant :DIGEST
+
+      class << self
+        # Determines whether or not the passed signature is valid for the given
+        # url, params, and files.
+        # @param signature [String]
+        #   The signature received from Phaxio.
+        # @param url [String]
+        #   The webhook URL used in this request.
+        # @param params [Hash]
+        #   The parameters received with the webhook, excluding files.
+        # @param files [Array<File>]
+        #   The files received with the webhook, if any.
+        # @return [true, false]
+        # @raise [Phaxio::Error::PhaxioError]
+        # @see https://www.phaxio.com/docs/security/callbacks
+        def valid_signature? signature, url, params, files = []
+          check_signature = generate_check_signature url, params, files
+          check_signature == signature
+        end
+
+        private
+
+        def generate_check_signature url, params, files = []
+          params_string = generate_params_string(params)
+          files_string = generate_files_string(files)
+          webhook_data = "#{url}#{params_string}#{files_string}"
+          OpenSSL::HMAC.hexdigest(DIGEST, webhook_token, webhook_data)
+        end
+
+        def webhook_token
+          Phaxio.webhook_token or raise(Error::PhaxioError, 'No webhook token has been set')
+        end
+
+        def generate_params_string(params)
+          sorted_params = params.sort_by { |key, _value| key }
+          params_strings = sorted_params.map { |key, value| "#{key}#{value}" }
+          params_strings.join
+        end
+
+        def generate_files_string(files)
+          files_array = files_to_array(files).reject(&:nil?)
+          sorted_files = files_array.sort_by { |file| file[:name] }
+          files_strings = sorted_files.map { |file| generate_file_string(file) }
+          files_strings.join
+        end
+
+        def files_to_array(files)
+          files.is_a?(Array) ? files : [files]
+        end
+
+        def generate_file_string(file)
+          file[:name] + DIGEST.hexdigest(file[:tempfile].read)
+        end
+      end
+    end
+  end
+end

data/lib/phaxio/version.rb

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

data/lib/phaxio.rb

@@ -17,7 +17,10 @@ Dir[File.expand_path(File.join('..', 'phaxio', 'helpers', '*.rb'), __FILE__)].ea
   require file
 end
 
-%w[fax_recipient fax account callback phax_code phone_number public ata].each do |filename|
+%w[
+  fax_recipient fax account callback webhook phax_code phone_number public ata
+  port_number_note port_number port_order
+].each do |filename|
   require File.expand_path(File.join('..', 'phaxio', 'resources', filename), __FILE__)
 end
 
@@ -29,11 +32,13 @@ module Phaxio
     #   @see Config.api_key
     # @!attribute api_secret
     #   @see Config.api_secret
+    # @!attribute webhook_token
+    #   @see Config.webhook_token
     # @!attribute callback_token
-    #   @see Config.callback_token
+    #   @see Config.webhook_token
     # @!attribute api_endpoint
     #   @see Config.api_endpoint
-    %w(api_key api_secret callback_token api_endpoint).each do |config_attribute|
+    %w(api_key api_secret webhook_token callback_token api_endpoint).each do |config_attribute|
       # Define getters
       define_method(config_attribute) do
         Config.public_send config_attribute
@@ -45,5 +50,9 @@ module Phaxio
         Config.public_send setter, value
       end
     end
+
+    # for backwards compatibility
+    alias callback_token  webhook_token
+    alias callback_token= webhook_token=
   end
 end

data/spec/client_spec.rb

@@ -19,6 +19,16 @@ RSpec.describe Phaxio::Client do
     )
   end
 
+  def test_response_503
+    instance_double(
+      Faraday::Response,
+      status: 503,
+      success?: false,
+      headers: {},
+      body: nil
+    )
+  end
+
   describe 'making a request' do
     it 'sends the request to Phaxio' do
       endpoint = 'public/countries/'
@@ -118,6 +128,13 @@ RSpec.describe Phaxio::Client do
       }.to raise_error(Phaxio::Error::RateLimitExceededError, '429: This is a test.')
     end
 
+    it 'raises a service unavailable error if the response status is 503' do
+      expect(test_connection).to receive(:get) { test_response_503 }
+      expect {
+        client.request :get, 'test'
+      }.to raise_error(Phaxio::Error::ServiceUnavailableError, '503: ')
+    end
+
     it 'raises a general error for if the response status is 5XX' do
       expect(test_connection).to receive(:get) { test_response 500 }
       expect {

data/spec/phaxio_spec.rb

@@ -13,8 +13,14 @@ RSpec.describe Phaxio do
     expect(subject.api_secret).to eq('test-api-secret')
   end
 
-  it 'sets the callback token' do
+  it 'sets the webhook token' do
+    subject.webhook_token = 'test-webhook-token'
+    expect(subject.webhook_token).to eq('test-webhook-token')
+  end
+
+  it 'sets and gets the webhook token as callback_token' do
     subject.callback_token = 'test-callback-token'
     expect(subject.callback_token).to eq('test-callback-token')
+    expect(subject.webhook_token).to eq('test-callback-token')
   end
 end

data/spec/resources/account_spec.rb

@@ -1,16 +1,10 @@
 require 'spec_helper'
 
 RSpec.describe Account do
-  describe 'getting account information' do
+  describe 'getting account information', vcr: 'account/get' do
     let(:action) { Account.get params }
     let(:params) { {} }
 
-    around do |example|
-      VCR.use_cassette('resources/account/status') do
-        example.run
-      end
-    end
-
     it 'sends the request to Phaxio' do
       expect_api_request :get, 'account/status', params
       action