Merge pull request #42 from phaxio/FAX-1989

Fax 1989

Author: jnankin

README.md

@@ -26,14 +26,14 @@ $ gem install phaxio
 
 ## Usage
 
-Set up your API Key, API Secret, and, optionally, Callback Token.
+Set up your API Key, API Secret, and, optionally, Webhook Token.
 
 ``` ruby
 require 'phaxio'
 
 Phaxio.api_key = '11111'
 Phaxio.api_secret = '22222'
-Phaxio.callback_token = '33333'
+Phaxio.webhook_token = '33333'
 ```
 
 Try sending a fax:
@@ -243,32 +243,32 @@ Account.get
 # => Account(balance: 1000, faxes_today: 0, faxes_this_month: 100)
 ```
 
-#### Callback
+#### Webhook
 
-##### `Callback.valid_signature?`
+##### `Webhook.valid_signature?`
 
-Validate the callback signature sent with a Phaxio callback. Requires that Phaxio.callback_token be
+Validate the webhook signature sent with a Phaxio webhook. Requires that Phaxio.webhook_token be
 set.
 
 ``` ruby
-Callback.valid_signature? received_signature, callback_url, received_params, received_files
+Webhook.valid_signature? received_signature, webhook_url, received_params, received_files
 # => true
 ```
 
-## Callback Validation Example with Sinatra
+## Webhook Validation Example with Sinatra
 
 ``` ruby
 require 'sinatra/base'
 require 'phaxio'
 
 class PhaxioWebhookExample < Sinatra::Base
-  Phaxio.callback_token = 'YOUR WEBHOOK TOKEN HERE'
-  
+  Phaxio.webhook_token = 'YOUR WEBHOOK TOKEN HERE'
+
   post '/webhook' do
     signature = request.env['HTTP_X_PHAXIO_SIGNATURE']
     url = request.url
     file_params = params[:file]
-    if Phaxio::Callback.valid_signature? signature, url, webhook_params, file_params
+    if Phaxio::Webhook.valid_signature? signature, url, webhook_params, file_params
       'Success'
     else
       'Invalid webhook signature'
@@ -289,22 +289,22 @@ end
 class WebhookController < ApplicationController
   skip_before_action :verify_authenticity_token
 
-	def index
+  def index
     signature = request.headers['X-Phaxio-Signature']  
-    Phaxio.callback_token = 'YOUR WEBHOOK TOKEN HERE'
+    Phaxio.webhook_token = 'YOUR WEBHOOK TOKEN HERE'
     url = request.original_url
 
     Rails.logger.debug "URL: " + url
     Rails.logger.debug "Signature: " + signature
     Rails.logger.debug "params: " + params.inspect
     Rails.logger.debug "webhook_params: " + webhook_params.to_h.inspect
-    
-    if Phaxio::Callback.valid_signature? signature, url, webhook_params.to_h, file_params
+
+    if Phaxio::Webhook.valid_signature? signature, url, webhook_params.to_h, file_params
       Rails.logger.debug "Success"
       render plain: 'Success'
     else
-      Rails.logger.debug "Invalid callback signature"
-      render plain: 'Invalid callback signature'
+      Rails.logger.debug "Invalid webhook signature"
+      render plain: 'Invalid webhook signature'
     end
   end
 

lib/phaxio.rb

@@ -18,7 +18,7 @@
 end
 
 %w[
-  fax_recipient fax account callback phax_code phone_number public ata
+  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__)
@@ -32,11 +32,13 @@ class << self
     #   @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
@@ -48,5 +50,9 @@ class << self
         Config.public_send setter, value
       end
     end
+
+    # for backwards compatibility
+    alias callback_token  webhook_token
+    alias callback_token= webhook_token=
   end
 end

lib/phaxio/config.rb

@@ -13,11 +13,13 @@ class << self
       # To find your API secret, visit https://console.phaxio.com/api_credentials
       attr_accessor :api_secret
 
-      # Your Phaxio callback token. This will be used to verify that callback requests are coming
+      # Your Phaxio webhook token. This will be used to verify that webhook requests are coming
       # from Phaxio.
       #
-      # To find your callback token, visit https://console.phaxio.com/user/callbacks/edit
-      attr_accessor :callback_token
+      # To find your webhook token, visit https://console.phaxio.com/user/callbacks/edit
+      attr_accessor :webhook_token
+      alias callback_token webhook_token
+      alias callback_token= webhook_token=
 
       # The Phaxio API endpoint. Users generally shouldn't need to change it.
       # Defaults to https://api.phaxio.com/v2.1/

lib/phaxio/resource.rb

@@ -139,12 +139,18 @@ class Collection
       #
       # @see Phaxio::Resource.response_collection
       def initialize response_data, resource
-        if response_data.key? 'paging'
-          self.total = response_data['paging']['total']
-          self.per_page = response_data['paging']['per_page']
-          self.page = response_data['paging']['page']
+        # For some endpoints we'll get a hash with `paging` and `data` attributes.
+        # For others, just an array.
+        if response_data.is_a? Hash
+          if response_data.key? 'paging'
+            self.total = response_data['paging']['total']
+            self.per_page = response_data['paging']['per_page']
+            self.page = response_data['paging']['page']
+          end
+          self.raw_data = response_data['data']
+        else
+          self.raw_data = response_data
         end
-        self.raw_data = response_data['data']
         self.collection = raw_data.map { |record_data| resource.response_record record_data }
       end
 

lib/phaxio/resources/ata.rb

@@ -20,17 +20,37 @@ class Ata < Resource
       # @return [String] The domain for the ATA.
       # @!attribute domain
 
+      # @return [String] The user agent for the ATA.
+      # @!attribute user_agent
+
+      # @return [String] The SIP URI for the ATA.
+      # @!attribute sip_uri
+
       # @return [String] The mac address for the ATA.
       # @!attribute mac_address
 
+      # @return [String] The name of the group which the ATA belongs to.
+      # @!attribute group
+
       # @return [String] The username for the ATA.
-      # @!attribute uername
+      # @!attribute username
 
       # @return [String] The password for the ATA.
       # @!attribute password
 
       has_normal_attributes %w[
-        id name description user_phone_number domain username password mac_address
+        id name description user_phone_number domain user_agent sip_uri
+        mac_address group username password
+      ]
+
+      # @return [Time] The time at which the ATA was last registered.
+      # @!attribute last_registered
+
+      # @return [Time] The time at which the ATA's registration expires.
+      # @!attribute expiry_time
+
+      has_time_attributes %w[
+        last_registered expiry_time
       ]
 
       # A reference to an ATA. This is returned by certain actions which don't
@@ -44,28 +64,48 @@ def to_i
           id
         end
 
+        # Gets the referenced ATA.
+        # @return [Phaxio::Resources::ATA]
+        def get
+          Ata.get self
+        end
+        alias :retrieve :get
+        alias :find :get
+
         private
 
         def initialize id
           self.id = id
         end
       end
 
-      # A reference to a phone number, returned by ATA phone number management
-      # actions.
-      class PhoneNumberReference
-        # @return [String]
-        #   The phone number.
-        attr_accessor :phone_number
+      # A set of provisioning URLs.
+      class ProvisioningURLs
+        # @return [Hash<String: String>] The hash of provisioning URLs. 
+        # @!attribute urls
+        attr_reader :urls
+
+        GRANDSTREAM = 'Grandstream'
+        OBI = 'OBi'
+        NETGEN = 'Netgen'
 
-        def to_s
-          phone_number
+        def initialize data
+          @urls = data
         end
 
-        private
+        # @return [String] The Grandstream provisioning url.
+        def grandstream
+          self.urls.fetch(GRANDSTREAM)
+        end
+
+        # @return [String] The OBi provisioning url.
+        def obi
+          self.urls.fetch(OBI)
+        end
 
-        def initialize phone_number
-          self.phone_number = phone_number
+        # @return [String] The Netgen provisioning url.
+        def netgen
+          self.urls.fetch(NETGEN)
         end
       end
 
@@ -103,7 +143,9 @@ def create params = {}
         # @param id [Integer]
         #   The ID of the ATA to retrieve information about.
         # @param params [Hash]
-        #   Any parameters to send to Phaxio. This action takes no unique parameters.
+        #   Any parameters to send to Phaxio.
+        #   - *with_credentials* [Boolean] - If enabled, the username and
+        #     password for the ATA will be included in the response.
         # @return [Phaxio::Resources::Ata]
         #   The requested ATA.
         # @raise [Phaxio::Error::PhaxioError]
@@ -148,7 +190,7 @@ def regenerate_credentials id, params = {}
 
         # Delete an ATA
         # @param id [Integer]
-        #   The Id of the ATA to delete.
+        #   The ID of the ATA to delete.
         # @param params [Hash]
         #   Any parameters to send to Phaxio. This action takes no unique parameters.
         # @return [Phaxio::Resources::Ata::Reference]
@@ -167,7 +209,7 @@ def delete id, params = {}
         #   The phone number to add to the ATA.
         # @param params [Hash]
         #   Any parameters to send to Phaxio. This action takes no unique parameters.
-        # @return [Phaxio::Resources::Ata::PhoneNumberReference]
+        # @return [Phaxio::Resources::PhoneNumber::Reference]
         #   A reference to the added phone number.
         # @raise [Phaxio::Error::PhaxioError]
         # @see https://www.phaxio.com/docs/api/v2.1/atas/add_phone_number
@@ -183,7 +225,7 @@ def add_phone_number id, phone_number, params = {}
         #   The phone number you want to remove.
         # @param params [Hash]
         #   Any parameters to send to Phaxio. This action takes no unique parameters.
-        # @return [Phaxio::Resources::Ata::PhoneNumberReference]
+        # @return [Phaxio::Resources::PhoneNumber::Reference]
         #   A reference to the removed phone number.
         # @raise [Phaxio::Error::PhaxioError]
         # @see https://www.phaxio.com/docs/api/v2.1/atas/remove_phone_number
@@ -192,14 +234,30 @@ def remove_phone_number id, phone_number, params = {}
           response_phone_number_reference response
         end
 
+        # Get ATA provisioning URLs for your Phaxio account.
+        # @param params [Hash]
+        #   Any parameters to send to Phaxio.
+        #   - *group* [String] - If given, this action instead returns
+        #     provisioning URLs for the named group.
+        # @return [Phaxio::Resources::Ata::ProvisioningURLs
+        # @see https://www.phaxio.com/docs/api/v2.1/atas/provisioning_urls
+        def provisioning_urls params = {}
+          response = Client.request :get, provisioning_urls_endpoint, params
+          response_provisioning_urls response
+        end
+
         private
 
         def response_reference response
           Reference.new Integer(response['id'])
         end
 
         def response_phone_number_reference response
-          PhoneNumberReference.new(response['phone_number'])
+          PhoneNumber::Reference.new(response['phone_number'])
+        end
+
+        def response_provisioning_urls response
+          ProvisioningURLs.new(response)
         end
 
         def atas_endpoint
@@ -217,6 +275,10 @@ def regenerate_credentials_endpoint id
         def phone_number_endpoint id, phone_number
           "#{ata_endpoint(id)}/phone_numbers/#{phone_number}"
         end
+
+        def provisioning_urls_endpoint
+          "#{atas_endpoint}/provisioning_urls"
+        end
       end
     end
   end