phaxio 0.5.0 → 2.0.0

data/lib/phaxio/config.rb

@@ -0,0 +1,31 @@
+module Phaxio
+  class Config
+    DEFAULT_API_ENDPOINT = 'https://api.phaxio.com/v2/'.freeze
+
+    class << self
+      # Your Phaxio API key. This will be used for all interactions with the Phaxio API.
+      #
+      # To find your API key, visit https://console.phaxio.com/api_credentials
+      attr_accessor :api_key
+
+      # Your Phaxio API secret. This will be used for all interactions with the Phaxio API.
+      #
+      # 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
+      # from Phaxio.
+      #
+      # To find your callback token, visit https://console.phaxio.com/user/callbacks/edit
+      attr_accessor :callback_token
+
+      # The Phaxio API endpoint. Users generally shouldn't need to change it.
+      # Defaults to https://api.phaxio.com/v2/
+      attr_writer :api_endpoint
+
+      def api_endpoint
+        @api_endpoint || DEFAULT_API_ENDPOINT
+      end
+    end
+  end
+end

data/lib/phaxio/error.rb

@@ -0,0 +1,13 @@
+module Phaxio
+  module Error
+    PhaxioError = Class.new StandardError
+    %w[
+      AuthenticationError
+      NotFoundError
+      InvalidRequestError
+      RateLimitExceededError
+      GeneralError
+      ApiConnectionError
+    ].each { |error_klass_name| const_set error_klass_name, Class.new(PhaxioError) }
+  end
+end

data/lib/phaxio/helpers/mime_type_helper.rb

@@ -0,0 +1,14 @@
+module Phaxio
+  # @api private
+  module MimeTypeHelper
+    class << self
+      def extension_for_mimetype mimetype
+        MIME::Types[mimetype].first.extensions.first
+      end
+
+      def mimetype_for_file file_path
+        MIME::Types.of(file_path).first.content_type
+      end
+    end
+  end
+end

data/lib/phaxio/resource.rb

@@ -0,0 +1,168 @@
+module Phaxio
+  # The base class for API resources, such as `Fax` and `PhoneNumber`.
+  #
+  # This class is considered an implementation detail, and shouldn't be directly relied upon by
+  # users.
+  #
+  # The only exception is that this class will continue to be the base class for all Phaxio
+  # resources, so checking whether a fax instance is a kind of Phaxio::Resource will always return
+  # true.
+  class Resource
+    private
+
+    # The raw response data
+    attr_accessor :raw_data
+
+    # Populates the instance's attributes based on the `raw_data`.
+    def populate_attributes
+      self.class.normal_attribute_list.each do |normal_attribute|
+        self.public_send "#{normal_attribute}=", raw_data[normal_attribute]
+      end
+
+      self.class.time_attribute_list.each do |time_attribute|
+        time = raw_data[time_attribute]
+        time = Time.parse(time) if !time.nil?
+        self.public_send "#{time_attribute}=", time
+      end
+
+      self.class.collection_attribute_mappings.each do |collection_attribute, klass|
+        collection = raw_data[collection_attribute] || []
+        collection = {'data' => collection}
+        collection = klass.response_collection(collection)
+        self.public_send "#{collection_attribute}=", collection
+      end
+    end
+
+    # @see Phaxio::Resource.response_record
+    def initialize raw_data
+      self.raw_data = raw_data
+      populate_attributes
+    end
+
+    class << self
+      # @api private
+      # Returns a new instance of the resource for this data.
+      # @param raw_data [Hash] The raw response data from Phaxio.
+      # @return [Phaxio::Resource] The resource instance.
+      def response_record raw_data
+        new raw_data
+      end
+
+      # @api private
+      # Returns a new collection of resource instances for this data.
+      # @param raw_data [Array] The raw response data from Phaxio.
+      # @return [Phaxio::Resource::Collection] A collection of Phaxio::Resource instances.
+      def response_collection raw_data
+        Collection.new raw_data, self
+      end
+
+      # @api private
+      # Full list of resource-specific attributes.
+      attr_accessor :attribute_list
+
+      # @api private
+      # List of resource-specific attributes that don't require additional processing during
+      # instance data population.
+      attr_accessor :normal_attribute_list
+
+      # @api private
+      # List of resource-specific attributes that must be parsed into a Time object during instance
+      # data population.
+      attr_accessor :time_attribute_list
+
+      # @api private
+      # Mapping of resource-specific attributes that must be parsed into a resource collection.
+      attr_accessor :collection_attribute_mappings
+
+      private :new
+
+      private
+
+      # Creates accessors for the given normal attributes and adds them to the class's internal
+      # attribute lists.
+      # @param attribute_list [Array]
+      #   A list of attributes as strings or symbols.
+      # @see Phaxio::Resource.normal_attribute_list
+      def has_normal_attributes attribute_list
+        attribute_list = attribute_list.map { |attribute_name| attribute_name.to_s.freeze }
+        attr_accessor *attribute_list
+        self.attribute_list += attribute_list
+        self.normal_attribute_list += attribute_list
+      end
+
+      # Creates accessors for the given time attributes and adds them to the class's internal
+      # attribute lists.
+      # @param attribute_list [Array]
+      #   A list of attributes as strings or symbols.
+      # @see Phaxio::Resource.time_attribute_list
+      def has_time_attributes attribute_list
+        attribute_list = attribute_list.map { |attribute_name| attribute_name.to_s.freeze }
+        attr_accessor *attribute_list
+        self.attribute_list += attribute_list
+        self.time_attribute_list += attribute_list
+      end
+
+      # Creates accessors for the given collection attributes and adds them to the class's internal
+      # attribute lists.
+      # @param attribute_hash [Hash<String, Symbol => Phaxio::Resource>]
+      #   A hash which has keys corresponding to the attribute name on this resource, and values
+      #   corresponding to the resource class for the collection's items.
+      # @see Phaxio::Resource.collection_attribute_mappings
+      def has_collection_attributes attribute_hash
+        # Array#to_h doesn't exist in 2.0.0, hence the inject here.
+        attribute_hash = attribute_hash
+          .map { |k, v| [ k.to_s.freeze, v ] }
+          .inject({}) { |memo, obj| memo.tap { |memo| memo[obj.first] = obj.last } }
+        attr_accessor *attribute_hash.keys
+        self.attribute_list += attribute_hash.keys
+        self.collection_attribute_mappings = self.collection_attribute_mappings.merge(attribute_hash)
+      end
+
+      # Use the inherited hook to dynamically set each subclass's attribute lists to empty arrays
+      # upon creation.
+      def inherited subclass
+        subclass.attribute_list = []
+        subclass.normal_attribute_list = []
+        subclass.time_attribute_list = []
+        subclass.collection_attribute_mappings = {}
+      end
+    end
+
+    class Collection
+      include Enumerable
+
+      # The raw response data
+      attr_accessor :raw_data, :collection, :total, :per_page, :page
+
+      # Returns a new collection of resource instances for this data. Generally this is not called
+      # directly.
+      #
+      # @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']
+        end
+        self.raw_data = response_data['data']
+        self.collection = raw_data.map { |record_data| resource.response_record record_data }
+      end
+
+      def [] idx
+        collection[idx]
+      end
+
+      def each(&block)
+        collection.each(&block)
+      end
+
+      def length
+        collection.length
+      end
+
+      def size
+        length
+      end
+    end
+  end
+end

data/lib/phaxio/resources.rb

@@ -0,0 +1,7 @@
+module Phaxio
+  # This module contains all Phaxio Resource classes. These have already been included into the
+  # Phaxio namespace, so you can write Phaxio::Fax instead of Phaxio::Resources::Fax. If that's
+  # still too verbose, you can `include Phaxio::Resources` to pull only these in.
+  module Resources
+  end
+end

data/lib/phaxio/resources/account.rb

@@ -0,0 +1,41 @@
+module Phaxio
+  module Resources
+    # Information about your Phaxio account.
+    class Account < Resource
+      ACCOUNT_PATH = 'account'
+      private_constant :ACCOUNT_PATH
+
+      # @return [Integer] Your current account funds balance in cents.
+      # @!attribute balance
+
+      # @return [Hash<String: Integer>] A hash of the number of faxes sent and received today.
+      # @!attribute faxes_today
+
+      # @return [Hash<String: Integer>] A hash of the number of faxes sent and received this month.
+      # @!attribute faxes_this_month
+      has_normal_attributes %w[balance faxes_today faxes_this_month]
+
+      class << self
+        # Get information about your Phaxio account, including your balance, number of faxes sent
+        # today, and number of faxes sent this week.
+        # @param params [Hash]
+        #   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
+        def get params = {}
+          response = Client.request :get, account_status_endpoint, params
+          response_record response
+        end
+        alias :status :get
+        alias :retrieve :get
+
+        private
+
+        def account_status_endpoint
+          "#{ACCOUNT_PATH}/status"
+        end
+      end
+    end
+  end
+end

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