phaxio 0.4.0 → 2.1.0.pre

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/ata.rb

@@ -0,0 +1,219 @@
+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 username for the ATA.
+      # @!attribute uername
+
+      # @return [String] The password for the ATA.
+      # @!attribute password
+
+      has_normal_attributes %w[
+        id name description user_phone_number domain username password
+      ]
+
+      # 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
+
+        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
+
+        def to_s
+          phone_number
+        end
+
+        private
+
+        def initialize phone_number
+          self.phone_number = phone_number
+        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.
+        # @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. This action takes no unique parameters.
+        # @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.
+        #   - *domain* [String] - A domain 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::Ata::PhoneNumberReference]
+        #   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::Ata::PhoneNumberReference]
+        #   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
+
+        private
+
+        def response_reference response
+          Reference.new Integer(response['id'])
+        end
+
+        def response_phone_number_reference response
+          PhoneNumberReference.new(response['phone_number'])
+        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
+      end
+    end
+  end
+end