phaxio 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 6a10449404bdb1df029a52a878f49202589e727d
-  data.tar.gz: f500188f94760b8300dc2f63b17eb4ad31edc5fa
+SHA256:
+  metadata.gz: 508fcbe635de23974bfdefe06aec6811fd7f91bd03377dd4a90b971cd1b6a44f
+  data.tar.gz: e33347de232350332fe604ecae8c0f511a3774fb9ef7c863f6a269bb53bad787
 SHA512:
-  metadata.gz: df06285d6e87fbc048f0ebcad0cd5ee608ccfb0b45c6813926f272c4302aa5dc60421445df11bacc6fae2e26a32951912ca201376a56c77bcd2e5fa71e0e5976
-  data.tar.gz: 9d5bcfa978e6e92317d17d4bb0a31e4cd2f33f57d96f8241721bc581be34c768623704d951d4a177f5634dc0eb6a7f2cff4c8db7588e6e286a61ba2aa5020dd3
+  metadata.gz: 6a041ed3d71f144ae2c2776a69be5d947982f1eb76c2a2e748f07b245d48ac8714c9199702b71a9b8c0cd404ea6318518834cb9da9365f569cc6b35633c66e83
+  data.tar.gz: d50baaa1fc873a3a20268fb0c56d1b902d0b922d8fcdb731d40e23d89c74bd9c6fea3e35aa66e8c7472502b5af7ac1ad060b5cec22d3fe244e816d98d9be10d5

data/Gemfile

@@ -4,10 +4,11 @@ gemspec
 
 group :development do
   gem 'bundler'
-  gem 'rake', '~> 10'
+  gem 'rake'
   gem 'rspec', '~> 3.7'
   gem 'vcr'
   gem 'webmock'
   gem 'pry'
   gem 'yard'
+  gem 'dotenv', require: false
 end

data/README.md

@@ -2,7 +2,7 @@
 
 [![Build Status](https://travis-ci.org/phaxio/phaxio-ruby.svg?branch=master)](https://travis-ci.org/phaxio/phaxio-ruby)
 
-A Ruby gem for interacting with the [Phaxio API](https://www.phaxio.com/docs/api/v2).
+A Ruby gem for interacting with the [Phaxio API](https://www.phaxio.com/docs/api/v2.1).
 
 ## Installation
 
@@ -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,45 +243,78 @@ 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 PhaxioCallbackExample < Sinatra::Base
-  Phaxio.config do |config|
-    config.api_key = '0123456789'
-    config.api_secret = '0123456789'
-    config.callback_token = '0123456789'
-  end
+class PhaxioWebhookExample < Sinatra::Base
+  Phaxio.webhook_token = 'YOUR WEBHOOK TOKEN HERE'
 
-  post '/phaxio_callback' do
+  post '/webhook' do
     signature = request.env['HTTP_X_PHAXIO_SIGNATURE']
     url = request.url
-    file_params = params[:filename]
-    if Phaxio::Callback.valid_signature? signature, url, callback_params, file_params
+    file_params = params[:file]
+    if Phaxio::Webhook.valid_signature? signature, url, webhook_params, file_params
       'Success'
     else
-      'Invalid callback signature'
+      'Invalid webhook signature'
     end
   end
 
-  def callback_params
+  def webhook_params
     params.select do |key, _value|
-      %w(success is_test direction fax metadata message).include?(key)
+      %w(success is_test direction fax metadata message event_type).include?(key)
+    end
+  end
+end
+```
+
+## Webhook Validation Example with Rails Controller
+
+``` ruby
+class WebhookController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def index
+    signature = request.headers['X-Phaxio-Signature']  
+    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::Webhook.valid_signature? signature, url, webhook_params.to_h, file_params
+      Rails.logger.debug "Success"
+      render plain: 'Success'
+    else
+      Rails.logger.debug "Invalid webhook signature"
+      render plain: 'Invalid webhook signature'
+    end
+  end
+
+  def webhook_params 
+    params.permit(:success, :is_test, :direction, :fax, :metadata, :event_type, :message)
+  end
+
+  def file_params 
+    if params[:file]
+      [{ :name => 'file', :tempfile => params[:file].tempfile }]
     end
   end
 end

data/lib/phaxio/client.rb

@@ -27,6 +27,7 @@ module Phaxio
         begin
           response = case method.to_s
                      when 'post' then post(endpoint, params)
+                     when 'patch' then patch(endpoint, params)
                      when 'get' then get(endpoint, params)
                      when 'delete' then delete(endpoint, params)
                      else raise ArgumentError, "HTTP method `#{method}` is not supported."
@@ -55,10 +56,7 @@ module Phaxio
           body = JSON.parse(response.body).with_indifferent_access
         else
           extension = MimeTypeHelper.extension_for_mimetype content_type
-          filename = File.join(
-            Dir.tmpdir,
-            Dir::Tmpname.make_tmpname('phaxio-', "download.#{extension}")
-          )
+          filename = File.join Dir.tmpdir, tmpname(extension)
           File.open(filename, 'wb') { |file| file.write response.body }
           body = {'success' => response.success?, 'data' => File.open(filename, 'rb')}
         end
@@ -93,28 +91,54 @@ module Phaxio
         end
       end
 
+      def tmpname(extension)
+        t = Time.now.strftime("%Y%m%d")
+        "phaxio-#{t}-#{$$}-#{rand(0x100000000).to_s(36)}-download.#{extension}"
+      end
+
       def post endpoint, params = {}
         # Handle file params
         params.each do |k, v|
           next unless k.to_s == 'file'
-          mime_type = MimeTypeHelper.mimetype_for_file v.path
-          params[k] = Faraday::UploadIO.new v, mime_type
+
+          if v.is_a? Array
+            file_param = v.map { |file| file_to_param file }
+          else
+            file_param = file_to_param v
+          end
+
+          params[k] = file_param
+        end
+
+        conn.post endpoint, params, api_headers(params)
+      end
+
+      def patch endpoint, params = {}
+        # Handle file params
+        params.each do |k, v|
+          next unless k.to_s == 'file'
+
+          if v.is_a? Array
+            file_param = v.map { |file| file_to_param file }
+          else
+            file_param = file_to_param v
+          end
+
+          params[k] = file_param
         end
 
-        conn.post endpoint, params
+        conn.patch endpoint, params, api_headers(params)
       end
 
       def get endpoint, params = {}
-        conn.get endpoint, params
+        conn.get endpoint, params, api_headers(params)
       end
 
       def delete endpoint, params = {}
-        conn.delete endpoint, params
+        conn.delete endpoint, params, api_headers(params)
       end
 
       def api_params params
-        params = default_params.merge params
-
         # Convert times to ISO 8601
         params.each do |k, v|
           next unless v.kind_of?(Time) || v.kind_of?(Date)
@@ -124,11 +148,17 @@ module Phaxio
         params
       end
 
-      def default_params
-        {
-          api_key: Phaxio.api_key,
-          api_secret: Phaxio.api_secret
-        }
+      def api_headers params
+        api_key    = params.delete(:api_key)    || Phaxio.api_key
+        api_secret = params.delete(:api_secret) || Phaxio.api_secret
+        return unless api_key && api_secret
+        auth = Base64.strict_encode64("#{api_key}:#{api_secret}")
+        {'Authorization' => "Basic #{auth}"}
+      end
+
+      def file_to_param file
+        mime_type = MimeTypeHelper.mimetype_for_file file.path
+        Faraday::UploadIO.new file, mime_type
       end
     end
   end

data/lib/phaxio/config.rb

@@ -1,6 +1,6 @@
 module Phaxio
   class Config
-    DEFAULT_API_ENDPOINT = 'https://api.phaxio.com/v2/'.freeze
+    DEFAULT_API_ENDPOINT = 'https://api.phaxio.com/v2.1/'.freeze
 
     class << self
       # Your Phaxio API key. This will be used for all interactions with the Phaxio API.
@@ -13,14 +13,16 @@ module Phaxio
       # 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/
+      # Defaults to https://api.phaxio.com/v2.1/
       attr_writer :api_endpoint
 
       def api_endpoint

data/lib/phaxio/resource.rb

@@ -139,12 +139,18 @@ module Phaxio
       #
       # @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
 

data/lib/phaxio/resources/account.rb

@@ -22,7 +22,7 @@ module Phaxio
         #   Any parameters to send to Phaxio. This action does not have any unique parameters.
         # @return [Phaxio::Resources::Acount] Your account information.
         # @raise [Phaxio::Error::PhaxioError]
-        # @see https://www.phaxio.com/docs/api/v2/account/status
+        # @see https://www.phaxio.com/docs/api/v2.1/account/status
         def get params = {}
           response = Client.request :get, account_status_endpoint, params
           response_record response

data/lib/phaxio/resources/ata.rb

@@ -0,0 +1,285 @@
+module Phaxio
+  module Resources
+    # Provides functionality for managing ATAs.
+    class Ata < Resource
+      ATAS_PATH = 'atas'.freeze
+      private_constant :ATAS_PATH
+
+      # @return [Integer] the ID of the ATA.
+      # @!attribute id
+
+      # @return [String] the name of the ATA.
+      # @!attribute name
+
+      # @return [String] the description of the ATA.
+      # @!attribute description
+
+      # @return [String] The user phone number associated with the ATA.
+      # @!attribute user_phone_number
+
+      # @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 username
+
+      # @return [String] The password for the ATA.
+      # @!attribute password
+
+      has_normal_attributes %w[
+        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
+      # return the full ATA.
+      class Reference
+        # @return [Integer]
+        #   The ID of the referenced ATA.
+        attr_accessor :id
+
+        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 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 initialize data
+          @urls = data
+        end
+
+        # @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
+
+        # @return [String] The Netgen provisioning url.
+        def netgen
+          self.urls.fetch(NETGEN)
+        end
+      end
+
+      class << self
+        # @macro paging
+        # List ATAs
+        # @param params[Hash]
+        #   Any parameters to send to Phaxio.
+        # @return [Phaxio::Resource::Collection<Phaxio::Resources::Ata>]
+        #   The collection of ATAs matching your request.
+        # @raise [Phaxio::Error::PhaxioError]
+        # @see https://www.phaxio.com/docs/api/v2.1/atas/list
+        def list params = {}
+          response = Client.request :get, atas_endpoint, params
+          response_collection response
+        end
+
+        # Create an ATA
+        # @param params [Hash]
+        #   Any parameters to send to Phaxio.
+        #   - *name* [String] - A name used to identify the ATA.
+        #   - *description* [String] - A longer description of the ATA.
+        #   - *domain* [String] - A domain for the ATA.
+        #   - *mac_address* [String] - A mac address for the ATA.
+        # @return [Phaxio::Resources::Ata]
+        #   The created ATA, including the generated username and password.
+        # @raise [Phaxio::Error::PhaxioError]
+        # @see https://www.phaxio.com/docs/api/v2.1/atas/create
+        def create params = {}
+          response = Client.request :post, atas_endpoint, params
+          response_record response
+        end
+
+        # Get an ATA
+        # @param id [Integer]
+        #   The ID of the ATA to retrieve information about.
+        # @param params [Hash]
+        #   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]
+        # @see https://www.phaxio.com/docs/api/v2.1/atas/get
+        def get id, params = {}
+          response = Client.request :get, ata_endpoint(id.to_i), params
+          response_record response
+        end
+        alias :retrieve :get
+        alias :find :get
+
+        # Update an ATA
+        # @param id [Integer]
+        #   The ID of the ATA to update.
+        # @param params [Hash]
+        #   Any parameters to send to Phaxio.
+        #   - *name* [String] - A name used to identify the ATA.
+        #   - *description* [String] - A longer description of the ATA.
+        #   - *mac_address* [String] - A mac address for the ATA.
+        # @return [Phaxio::Resources::Ata]
+        #   The updated ATA.
+        # @raise [Phaxio::Error::PhaxioError]
+        # @see https://www.phaxio.com/docs/api/v2.1/atas/update
+        def update id, params = {}
+          response = Client.request :patch, ata_endpoint(id.to_i), params
+          response_record response
+        end
+
+        # Regenerate credentials for an ATA
+        # @param id [Integer]
+        #   The ID of the ATA for which credentials should be regenerated.
+        # @param params [Hash]
+        #   Any parameters to send to Phaxio. This action takes no unique parameters.
+        # @return [Phaxio::Resources::Ata]
+        #   The ATA, including the new username and password.
+        # @raise Phaxio::Error::PhaxioError
+        # @see https://www.phaxio.com/docs/api/v2.1/atas/regenerate_credentials
+        def regenerate_credentials id, params = {}
+          response = Client.request :patch, regenerate_credentials_endpoint(id.to_i), params
+          response_record response
+        end
+
+        # Delete an ATA
+        # @param id [Integer]
+        #   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]
+        #   A reference to the deleted ATA.
+        # @raise [Phaxio::Error::PhaxioError]
+        # @see https://www.phaxio.com/docs/api/v2.1/atas/delete
+        def delete id, params = {}
+          response = Client.request :delete, ata_endpoint(id.to_i), params
+          response_reference response
+        end
+
+        # Add a phone number
+        # @param id [Integer]
+        #   The ID of the ATA to which you want to add a number.
+        # @param phone_number [String]
+        #   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::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
+        def add_phone_number id, phone_number, params = {}
+          response = Client.request :post, phone_number_endpoint(id, phone_number), params
+          response_phone_number_reference response
+        end
+
+        # Remove a phone number
+        # @param id [Integer]
+        #   The ID of the ATA from which you want to remove the phone number.
+        # @param phone_number [String]
+        #   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::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
+        def remove_phone_number id, phone_number, params = {}
+          response = Client.request :delete, phone_number_endpoint(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
+          PhoneNumber::Reference.new(response['phone_number'])
+        end
+
+        def response_provisioning_urls response
+          ProvisioningURLs.new(response)
+        end
+
+        def atas_endpoint
+          ATAS_PATH
+        end
+
+        def ata_endpoint id
+          "#{atas_endpoint}/#{id}"
+        end
+
+        def regenerate_credentials_endpoint id
+          "#{ata_endpoint(id)}/regenerate_credentials"
+        end
+
+        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
+end

data/lib/phaxio/resources/callback.rb

@@ -1,63 +1,17 @@
 module Phaxio
   module Resources
-    # Provides utilities for working with callbacks.
-    # @see https://www.phaxio.com/docs/api/v2/faxes/send_callback
-    # @see https://www.phaxio.com/docs/api/v2/faxes/receive_callback
+    # This class is provided for the sake of backwards compatibility; use the Webhook resource instead.
+    # @see Phaxio::Resources::Webhook
     class Callback
-      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 callback URL used in this request.
-        # @param params [Hash]
-        #   The parameters received with the callback, excluding files.
-        # @param files [Array<File>]
-        #   The files received with the callback, 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)
-          callback_data = "#{url}#{params_string}#{files_string}"
-          OpenSSL::HMAC.hexdigest(DIGEST, callback_token, callback_data)
-        end
-
-        def callback_token
-          Phaxio.callback_token or raise(Error::PhaxioError, 'No callback 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)
+        def valid_signature? *args
+          Phaxio::Resources::Webhook.valid_signature? *args
+        rescue Error::PhaxioError => error
+          if error.message == 'No webhook token has been set'
+            raise Error::PhaxioError, 'No callback token has been set'
+          else
+            raise error
+          end
         end
       end
     end