Implement port orders API

Author: jtnegrotto

lib/phaxio.rb

@@ -17,7 +17,10 @@
   require file
 end
 
-%w[fax_recipient fax account callback phax_code phone_number public ata].each do |filename|
+%w[
+  fax_recipient fax account callback 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
 

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

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

lib/phaxio/resources/port_order.rb

@@ -0,0 +1,155 @@
+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 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 name_on_account name_of_business provider_name
+        billing_number billing_address1 billing_address2
+        billing_city billing_state billing_zip esig legal_agreement
+      ]
+
+      # @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.
+        #   - *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

spec/resources/port_number_note_spec.rb

@@ -0,0 +1,26 @@
+require 'spec_helper'
+
+RSpec.describe PortNumberNote do
+  describe 'getting a list of notes' do
+    let(:action) { PortNumberNote.get port_number_id, params }
+    let(:port_number_id) { 1234 }
+    let(:params) { {} }
+
+    around do |example|
+      VCR.use_cassette('resources/port_number_note/get') do
+        example.run
+      end
+    end
+
+    it 'makes the request to phaxio' do
+      expect_api_request :get, "port_numbers/#{id}/notes", params
+      action
+    end
+
+    it 'returns a collection of port number note objects' do
+      result = action
+      expect(result).to be_a(Phaxio::Resource::Collection)
+      expect(result.first).to be_a(PortNumberNote)
+    end
+  end
+end

spec/resources/port_number_spec.rb

@@ -0,0 +1,25 @@
+require 'spec_helper'
+
+RSpec.describe PortNumber do
+  describe 'getting information about a number' do
+    let(:action) { PortNumber.get id, params }
+    let(:id) { 1234 }
+    let(:params) { {} }
+
+    around do |example|
+      VCR.use_cassette('resources/port_number/get') do
+        example.run
+      end
+    end
+
+    it 'makes the request to phaxio' do
+      expect_api_request :get, "port_numbers/#{id}", params
+      action
+    end
+
+    it 'returns a port number object' do
+      result = action
+      expect(result).to be_a(PortNumber)
+    end
+  end
+end

spec/resources/port_order_spec.rb

@@ -0,0 +1,78 @@
+require 'spec_helper'
+
+RSpec.describe PortOrder do
+  describe 'creating an order' do
+    let(:action) { PortOrder.create params }
+    let(:params) {
+      {
+        port_numbers: ['+12251231234'],
+        contact_number: '+12251231234',
+        name_on_account: 'THIS IS A TEST',
+        provider_name: 'DO NOT PORT --Julien',
+        has_bill: true,
+        legal_agreement: true,
+        esig: 'NOT A VALID SIGNATURE'
+      }
+    }
+
+    around do |example|
+      VCR.use_cassette('resources/port_order/create') do
+        example.run
+      end
+    end
+
+    it 'makes the request to Phaxio' do
+      expect_api_request :post, 'port_orders', params
+      action
+    end
+
+    it 'returns a port order object' do
+      result = action
+      expect(result).to be_a(PortOrder)
+    end
+  end
+  
+  describe 'getting information about an order' do
+    let(:action) { PortOrder.get id, params }
+    let(:id) { 1234 }
+    let(:params) { {} }
+
+    around do |example|
+      VCR.use_cassette('resources/port_order/get') do
+        example.run
+      end
+    end
+
+    it 'makes the request to Phaxio' do
+      expect_api_request :get, "port_orders/#{id}", params
+      action
+    end
+
+    it 'returns a port order object' do
+      result = action
+      expect(result).to be_a(PortOrder)
+    end
+  end
+
+  describe 'listing port orders' do
+    let(:action) { PortOrder.list params }
+    let(:params) { {} }
+
+    around do |example|
+      VCR.use_cassette('resources/port_order/list') do
+        example.run
+      end
+    end
+
+    it 'makes the request to Phaxio' do
+      expect_api_request :get, 'port_orders', params
+      action
+    end
+
+    it 'returns a collection of port order objects' do
+      result = action
+      expect(result).to be_a(Phaxio::Resource::Collection)
+      expect(result.first).to be_a(PortOrder)
+    end
+  end
+end