phaxio 2.1.0.pre → 2.1.0

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.0"
 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/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

data/spec/resources/ata_spec.rb

@@ -0,0 +1,207 @@
+require 'spec_helper'
+
+RSpec.describe Ata do
+  describe Ata::Reference, vcr: 'ata/reference' do
+    let(:reference) { Ata::Reference.new ata_id }
+    let(:ata_id) { Ata.create(name: 'Test ATA').id }
+
+    describe '#get' do
+      it 'returns information about the referenced ATA' do
+        result = reference.get
+        expect(result).to be_a(Ata)
+        expect(result.name).to eq('Test ATA')
+      end
+    end
+  end
+
+  describe Ata::ProvisioningURLs, vcr: 'ata/provisioning_urls' do
+    let(:provisioning_urls) { Ata.provisioning_urls }
+
+    describe '#urls' do
+      it 'returns the full hash of provisioning URLS' do
+        expect(provisioning_urls.urls).to be_a(Hash)
+        expect(provisioning_urls.urls.keys).to match_array([
+          'OBi',
+          'Grandstream',
+          'Netgen',
+        ])
+      end
+    end
+
+    describe '#grandstream' do
+      it 'returns the grandstream provisioning URL' do
+        url = provisioning_urls.urls['Grandstream']
+        expect(provisioning_urls.grandstream).to eq(url)
+      end
+    end
+
+    describe '#obi' do
+      it 'returns the obi provisioning URL' do
+        url = provisioning_urls.urls['OBi']
+        expect(provisioning_urls.obi).to eq(url)
+      end
+    end
+
+    describe '#netgen' do
+      it 'returns the netgen provisioning url' do
+        url = provisioning_urls.urls['Netgen']
+        expect(provisioning_urls.netgen).to eq(url)
+      end
+    end
+  end
+
+  describe 'getting a list of ATAs', vcr: 'ata/list' do
+    let(:action) { Ata.list params }
+    let(:params) { {} }
+
+    it 'sends the request to phaxio' do
+      expect_api_request :get, 'atas', params
+      action
+    end
+
+    it 'returns a collection of ATAs' do
+      result = action
+      expect(result).to be_a(Ata::Collection)
+    end
+  end
+
+  describe 'creating an ATA', vcr: 'ata/create' do
+    let(:action) { Ata.create params }
+    let(:params) { {name: 'Test ATA'} }
+
+    it 'sends the request to phaxio' do
+      expect_api_request :post, 'atas', name: 'Test ATA'
+      action
+    end
+
+    it 'returns information about the created ATA' do
+      result = action
+      expect(result).to be_a(Ata)
+      expect(result.name).to eq('Test ATA')
+    end
+  end
+
+  describe 'getting information about an ATA', vcr: 'ata/get' do
+    let(:action) { Ata.get ata_id, params }
+    let(:ata_id) { Ata.create(name: 'Test ATA').id }
+    let(:params) { {} }
+
+    it 'sends the request to phaxio' do
+      expect_api_request :get, "atas/#{ata_id}", params
+      action
+    end
+
+    it 'returns information about the ATA' do
+      result = action
+      expect(result).to be_a(Ata)
+      expect(result.name).to eq('Test ATA')
+    end
+  end
+
+  describe 'updating an ATA', vcr: 'ata/update' do
+    let(:action) { Ata.update ata_id, params }
+    let(:ata_id) { Ata.create(name: 'Test ATA').id }
+    let(:params) { {name: 'New Name'} }
+
+    it 'sends the request to phaxio' do
+      expect_api_request :patch, "atas/#{ata_id}", params
+      action
+    end
+
+    it 'returns information about the updated ATA' do
+      result = action
+      expect(result).to be_a(Ata)
+      expect(result.name).to eq('New Name')
+    end
+  end
+
+  describe 'regenerating ATA credentials', vcr: 'ata/regenerate' do
+    let(:action) { Ata.regenerate_credentials ata_id, params }
+    let(:ata) { Ata.create(name: 'Test ATA') }
+    let(:ata_id) { ata.id }
+    let(:params) { {} }
+
+    it 'sends the request to phaxio' do
+      expect_api_request :patch, "atas/#{ata_id}/regenerate_credentials", params
+      action
+    end
+
+    it 'returns information about the ATA' do
+      original_username = ata.username
+      # some actions don't return full creds; creation does, but run a sanity check just in case
+      expect(original_username).to_not be_nil
+      result = action
+      expect(result).to be_a(Ata)
+      expect(result.username).to_not eq(original_username)
+      expect(result.username).to_not be_nil
+    end
+  end
+
+  describe 'deleting an ATA', vcr: 'ata/delete' do
+    let(:action) { Ata.delete ata_id, params }
+    let(:ata_id) { Ata.create(name: 'Test ATA').id }
+    let(:params) { {} }
+
+    it 'sends the request to phaxio' do
+      expect_api_request :delete, "atas/#{ata_id}", params
+      action
+    end
+
+    it 'returns a reference to the deleted ATA' do
+      result = action
+      expect(result).to be_a(Ata::Reference)
+      expect(result.id).to eq(ata_id)
+    end
+  end
+
+  describe 'adding a phone number to an ATA', vcr: 'ata/add_phone_number' do
+    let(:action) { Ata.add_phone_number ata_id, TEST_NUMBER, params }
+    let(:ata_id) { Ata.create(name: 'Test ATA').id }
+    let(:params) { {} }
+
+    it 'sends the request to phaxio' do
+      expect_api_request :post, "atas/#{ata_id}/phone_numbers/#{TEST_NUMBER}", params
+      action
+    end
+
+    it 'returns a reference to the added phone number' do
+      result = action
+      expect(result).to be_a(PhoneNumber::Reference)
+    end
+  end
+
+  describe 'removing a phone number from an ATA', vcr: 'ata/remove_phone_number' do
+    let(:action) { Ata.remove_phone_number ata_id, TEST_NUMBER, params }
+    let(:ata_id) { Ata.create(name: 'Test ATA').id }
+    let(:params) { {} }
+
+    before do
+      Ata.add_phone_number ata_id, TEST_NUMBER
+    end
+
+    it 'sends the request to phaxio' do
+      expect_api_request :delete, "atas/#{ata_id}/phone_numbers/#{TEST_NUMBER}", params
+      action
+    end
+
+    it 'returns a reference to the removed phone number' do
+      result = action
+      expect(result).to be_a(PhoneNumber::Reference)
+    end
+  end
+
+  describe 'listing provisioning URLs for an ATA', vcr: 'ata/provisioning_urls' do
+    let(:action) { Ata.provisioning_urls params }
+    let(:params) { {} }
+
+    it 'sends the request to phaxio' do
+      expect_api_request :get, "atas/provisioning_urls", params
+      action
+    end
+
+    it 'returns a set of provisioning URLs' do
+      response = action
+      expect(response).to be_a(Ata::ProvisioningURLs)
+    end
+  end
+end