phaxio 0.4.0 → 2.1.0.pre

data/lib/phaxio/resources/callback.rb

@@ -0,0 +1,65 @@
+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
+    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)
+        end
+      end
+    end
+  end
+end

data/lib/phaxio/resources/fax.rb

@@ -0,0 +1,310 @@
+module Phaxio
+  module Resources
+    # Provides functionality for viewing and managing faxes.
+    class Fax < Resource
+      FAXES_PATH = 'faxes'.freeze
+      private_constant :FAXES_PATH
+
+      # @return [Integer] the ID associated with this fax.
+      # @!attribute id
+
+      # @return ["sent" | "received"] the direction of the fax.
+      # @!attribute direction
+
+      # @return [Integer] the number of pages in the fax.
+      # @!attribute num_pages
+
+      # @return [Integer] the cost of the fax in cents.
+      # @!attribute cost
+
+      # @return [String] the status of the fax.
+      # @!attribute status
+
+      # @return [true | false]
+      #   an indication of whether or not this is a test fax.
+      # @!attribute is_test
+
+      # @return [String]
+      #   for sent faxes only, the number set as the Caller ID when sending the
+      #   fax.
+      # @!attribute caller_id
+
+      # @return [String]
+      #   for received faxes only, the sender's E.164 phone number.
+      # @!attribute from_number
+
+      # @return [String]
+      #   for received faxes only, the Phaxio phone number that was used to
+      #   receive the call.
+      # @!attribute to_number
+
+      # @return [String]
+      #   one of the Phaxio error types. Will give you a general idea of what
+      #   went wrong for a failed fax.
+      # @!attribute error_type
+
+      # @return [String]
+      #   a more detailed description of what went wrong for a failed fax.
+      # @!attribute error_message
+
+      # @return [Integer]
+      #   a numeric error code that corresponds to the error message, if any.
+      # @!attribute error_id
+
+      # @return [Hash]
+      #   a hash of tag name and value pairs. If a fax was sent with tag
+      #   metadata, it will appear here.
+      # @!attribute tags
+      has_normal_attributes %w[
+        id direction num_pages cost status is_test caller_id from_number
+        to_number error_type error_message error_id tags
+      ]
+
+      # @return [Time]
+      #   the time the fax was created.
+      # @!attribute created_at
+
+      # @return [Time]
+      #   the time the fax was completed.
+      # @!attribute completed_at
+
+      has_time_attributes %w[created_at completed_at]
+
+      # @return [Phaxio::Resource::Collection<Phaxio::Resources::FaxRecipient>]
+      #   a collection of this fax's recipients.
+      # @!attribute recipients
+
+      has_collection_attributes({recipients: FaxRecipient})
+
+      # A reference to a fax. This is returned by certain actions which don't
+      # return the full fax.
+      class Reference
+        # @return [Integer]
+        #   The ID of the fax being referenced.
+        attr_accessor :id
+
+        # Gets the referenced fax.
+        # @return [Phaxio::Resource::Fax]
+        #   The referenced Fax.
+        def get
+          Fax.get self
+        end
+        alias :retrieve :get
+        alias :find :get
+
+        def to_i
+          id
+        end
+
+        private
+
+        def initialize id
+          self.id = id
+        end
+      end
+
+      class << self
+        # @macro paging
+        # List faxes in date range.
+        # @param params [Hash]
+        #   Any parameters to send to Phaxio.
+        #   - *direction* [String] - Either "sent" or "received". Limits results
+        #     to faxes with the specified direction.
+        #   - *status* [String] - Limits results to faxes with the specified
+        #     status.
+        #   - *phone_number* [String] - A phone number in E.164 format that you
+        #     want to use to filter results. The phone number must be an exact
+        #     match, not a number fragment.
+        #   - *tag* [Hash<String: String>] - A tag name and value that you want
+        #     to use to filter results.
+        # @return [Phaxio::Resource::Collection<Phaxio::Resources::Fax>]
+        #   The collection of faxes matching your request.
+        # @raise [Phaxio::Error::PhaxioError]
+        # @see https://www.phaxio.com/docs/api/v2/faxes/list_faxes
+        def list params = {}
+          response = Client.request :get, faxes_endpoint, params
+          response_collection response
+        end
+
+        # Create and send a fax.
+        # @param params [Hash]
+        #   Any parameters to send to Phaxio. At least one *to* number is
+        #   required, as well as at least one *file* or *content_url*.
+        #   - *to* [String | Array<String>] - One or more phone numbers in E.164
+        #     format where this fax should be sent.
+        #   - *file* [File | Array<File>] - The fax file(s) to be sent.
+        #   - *content_url* [String, Array<String>] - URL(s) to be rendered and
+        #     sent as the fax content. If the *file* param is included as well,
+        #     URL content will come first in the transmitted files.
+        #   - *header_text* [String] - Text that will be displayed at the top of
+        #     each page of the fax. 50-character maximum. Defaults to "-".
+        #   - *batch_delay* [Integer] - Enabled batching and specifies the
+        #     amount of time, in seconds, before the batch is fired. Max is 3600
+        #     (one hour).
+        #   - *batch_collision_avoidance* [true | false] - When *batch_delay* is
+        #     set, the fax will be blocked until the receiving machine is no
+        #     longer busy.
+        #   - *callback_url* [String] - You can specify a callback URL that will
+        #     override one set globally in your account.
+        #   - *cancel_timeout* [Integer] - Number of minutes after which the fax
+        #     will be canceled if it hasn't yet completed. Must be between 3 and
+        #     \60. Additionally, for faxes with *batch_delay* set, it must be at
+        #     least 3 minutes after the *batch_delay*. If not, it will be
+        #     automatically extended when batching.
+        #   - *tag* [Hash<String: Object>] - A tag that contains metadata
+        #     relevant to your application. For example, you may wish to tag a
+        #     fax with an order id in your application. You could pass Phaxio
+        #     the following parameter: +tag: {order_id: 1234}+. You may specify
+        #     up to 10 tags.
+        # @return [Phaxio::Resources::Fax]
+        #   The created fax.
+        # @raise [Phaxio::Error::PhaxioError]
+        # @see https://www.phaxio.com/docs/api/v2/faxes/create_and_send_fax
+        # @see https://www.phaxio.com/docs/api/v2/faxes/batching
+        def create params = {}
+          response = Client.request :post, faxes_endpoint, params
+          response_reference response
+        end
+        alias :send :create
+
+        # Get fax info.
+        # @param id [Integer]
+        #   The ID of the fax to retrieve information about.
+        # @param params [Hash]
+        #   A hash of parameters to send to Phaxio. This action takes no unique parameters.
+        # @return [Phaxio::Resource::Fax] The requested fax.
+        # @raise [Phaxio::Error::PhaxioError]
+        # @see https://www.phaxio.com/docs/api/v2/faxes/get_fax
+        def get id, params = {}
+          response = Client.request :get, fax_endpoint(id.to_i), params
+          response_record response
+        end
+        alias :retrieve :get
+        alias :find :get
+
+        # Cancel a fax.
+        # @param id [Integer]
+        #   The ID of the fax to cancel.
+        # @param params [Hash]
+        #   A hash of parameters to send to Phaxio. This action takes no unique
+        #   parameters.
+        # @return [Phaxio::Resources::Fax::Reference]
+        #   A reference to the canceled fax.
+        # @raise [Phaxio::Error::PhaxioError]
+        # @see https://www.phaxio.com/docs/api/v2/faxes/cancel
+        def cancel id, params = {}
+          response = Client.request :post, cancel_fax_endpoint(id), params
+          response_reference response
+        end
+
+        # Resend a fax.
+        # @param id [Integer]
+        #   The ID of the fax to resend.
+        # @param params [Hash]
+        #   A hash of parameters to send to Phaxio.
+        #   - *callback_url* [String] - This parameter may be used to set a
+        #     different callback URL for the new fax.
+        # @return [Phaxio::Resources::Fax::Reference]
+        #   A reference to the resent fax.
+        # @raise [Phaxio::Error::PhaxioError]
+        # @see https://www.phaxio.com/docs/api/v2/faxes/resend
+        def resend id, params = {}
+          response = Client.request :post, resend_fax_endpoint(id), params
+          response_reference response
+        end
+
+        # Delete a fax. May only be used with test API credentials.
+        # @param id [Integer]
+        #   The ID of the fax to delete.
+        # @param params [Hash]
+        #   A hash of parameters to send to Phaxio. This action takes no unique
+        #   parameters.
+        # @return [true]
+        # @raise [Phaxio::Error::PhaxioError]
+        # @see https://www.phaxio.com/docs/api/v2/faxes/delete_fax
+        def delete id, params = {}
+          Client.request :delete, fax_endpoint(id), params
+          true
+        end
+
+        # Delete fax files.
+        # @param id [Integer]
+        #   The ID of the fax for which you want to delete files.
+        # @param params [Hash]
+        #   A hash of parameters to send to Phaxio. This action takes no unique
+        #   parameters.
+        # @return [true]
+        # @raise [Phaxio::Error::PhaxioError]
+        # @see https://www.phaxio.com/docs/api/v2/faxes/delete_fax_file
+        def delete_file id, params = {}
+          Client.request :delete, fax_file_endpoint(id), params
+          true
+        end
+
+        # Get fax content file or thumbnail.
+        # @param id [Integer]
+        #   The ID of the fax for which you want to get a file.
+        # @param params [Hash]
+        #   A hash of parameters to send to Phaxio.
+        #   - *thumbnail* ["s" | "l"] - If set to +"s"+ (small) or +"l"+
+        #     (large), a thumbnail of the requested size will be returned.
+        #     If unset, returns a PDF of the fax image.
+        # @return [File]
+        #   The requested fax file.
+        # @raise [Phaxio::Error::PhaxioError]
+        # @see https://www.phaxio.com/docs/api/v2/faxes/get_fax_file
+        def file id, params = {}
+          Client.request :get, fax_file_endpoint(id), params
+        end
+
+        # Test receiving a fax. May only be used with test API credentials.
+        # @param params [Hash]
+        #   A hash of parameters to send to Phaxio.
+        #   - *file* [File] - A PDF file to simulate receiving.
+        #   - *from_number* [String] - The phone number of the simulated sender
+        #     in E.164 format. Default is the public Phaxio phone number.
+        #   - *to_number* [String] - The phone number, in E.164 format, that is
+        #     receiving the fax. Specifically, a Phaxio phone number in your
+        #     account that is "receiving" the fax, or the public Phaxio phone
+        #     number. Default is the public Phaxio phone number.
+        # @return [true]
+        # @raise [Phaxio::Error::PhaxioError]
+        # @see https://www.phaxio.com/docs/api/v2/faxes/test_receive
+        def test_receive params = {}
+          Client.request :post, faxes_endpoint, test_receive_params(params)
+          true
+        end
+
+        private
+
+        def response_reference response
+          Reference.new response['id']
+        end
+
+        def faxes_endpoint
+          FAXES_PATH
+        end
+
+        def fax_endpoint id
+          "#{FAXES_PATH}/#{id}"
+        end
+
+        def fax_file_endpoint id
+          "#{fax_endpoint(id)}/file"
+        end
+
+        def cancel_fax_endpoint id
+          "#{fax_endpoint(id)}/cancel"
+        end
+
+        def resend_fax_endpoint id
+          "#{fax_endpoint(id)}/resend"
+        end
+
+        def test_receive_params params
+          {direction: 'received'}.merge(params)
+        end
+      end
+    end
+  end
+end

data/lib/phaxio/resources/fax_recipient.rb

@@ -0,0 +1,41 @@
+module Phaxio
+  module Resources
+    class FaxRecipient < Resource
+      # @return [String] The phone number of the recipient in E.164 format.
+      # @!attribute phone_number
+
+      # @return [String] The status of the recipient.
+      # @!attribute status
+
+      # @return [Integer] The number of retries for this recipient.
+      # @!attribute retry_count
+
+      # @return [Integer] The bitrate in bits/second that the fax was transmitted at.
+      # @!attribute bitrate
+
+      # @return [Integer]
+      #   The horizontal resolution that the fax was transmitted at in pixels per meter.
+      # @!attribute resolution
+
+      # @return [String]
+      #   One of the Phaxio Error types. Will give you a general idea of what went wrong for this
+      #   recipient.
+      # @!attribute error_type
+
+      # @return [String] A more detailed description of what went wrong for this receipient.
+      # @!attribute error_message
+
+      # @return [Integer] A numeric error code that corresponds to the error message, if any.
+      # @!attribute error_id
+
+      has_normal_attributes %w[
+        phone_number status retry_count bitrate resolution error_type error_message error_id
+      ]
+
+      # @return [Time] The time the job was completed for this recipient.
+      # @!attribute completed_at
+
+      has_time_attributes %w[completed_at]
+    end
+  end
+end

data/lib/phaxio/resources/phax_code.rb

@@ -0,0 +1,89 @@
+module Phaxio
+  module Resources
+    # Provides functionality for viewing and managing PhaxCodes.
+    class PhaxCode < Resource
+      PHAX_CODES_PATH = 'phax_codes'.freeze
+      DEFAULT_PHAX_CODE_PATH = 'phax_code'.freeze
+      private_constant :PHAX_CODES_PATH, :DEFAULT_PHAX_CODE_PATH
+
+      # @return [String] The identifier for the PhaxCode.
+      # @!attribute identifier
+
+      # @return [String] The metadata associated with the PhaxCode.
+      # @!attribute metadata
+
+      has_normal_attributes %w[identifier metadata]
+
+      # @return [Time] The time that the PhaxCode was created.
+      # @!attribute created_at
+
+      has_time_attributes %w[created_at]
+
+      class << self
+        # Create a PhaxCode.
+        # @param params [Hash]
+        #   A hash of parameters to send to Phaxio.
+        #   - *metadata* [String] - Metadata to be associated with the PhaxCode.
+        #   - *type* [String] - If set to "png", this method will return a PNG
+        #     file instead of a PhaxCode object.
+        # @return [Phaxio::Resources::PhaxCode | File] The created PhaxCode
+        # @raise [Phaxio::Error::PhaxioError]
+        # @see https://www.phaxio.com/docs/api/v2/phaxcodes/create_phax_code
+        def create params = {}
+          endpoint = case (params[:type] || params['type']).to_s
+            when 'png' then phax_codes_endpoint_png
+            else phax_codes_endpoint
+          end
+          result = Client.request :post, endpoint, params
+          return result if result.is_a? File
+          response_record result
+        end
+
+        # Retrieve a PhaxCode.
+        # @param params [Hash]
+        #   A hash of parameters to send to Phaxio.
+        #   - *identifier* [String] - The identifier for the PhaxCode you want to get. If blank, the
+        #     default PhaxCode will be returned.
+        #   - *type* [String] - If set to "png", this method will return a PNG file instead of a
+        #     PhaxCode object.
+        # @return [Phaxio::Resources::PhaxCode | File]
+        # @raise [Phaxio::Error::PhaxioError]
+        # @see https://www.phaxio.com/docs/api/v2/phaxcodes/retrieve_phax_code
+        def get params = {}
+          identifier = params[:identifier] || params['identifier']
+          endpoint = case (identifier)
+            when nil then default_phax_code_path
+            else phax_code_endpoint(identifier)
+          end
+          endpoint = case (params[:type] || params['type']).to_s
+            when 'png' then "#{endpoint}.png"
+            else endpoint
+          end
+          result = Client.request :get, endpoint, {}
+          return result if result.is_a? File
+          response_record result
+        end
+        alias :find :get
+        alias :retrieve :get
+
+        private
+
+        def phax_codes_endpoint
+          PHAX_CODES_PATH
+        end
+
+        def phax_codes_endpoint_png
+          "#{phax_codes_endpoint}.png"
+        end
+
+        def phax_code_endpoint(identifier)
+          "#{phax_codes_endpoint}/#{identifier}"
+        end
+
+        def default_phax_code_path
+          DEFAULT_PHAX_CODE_PATH
+        end
+      end
+    end
+  end
+end