phaxio 0.4.0 → 2.1.0.pre

data/lib/phaxio/client.rb

@@ -1,259 +1,169 @@
+# @!macro [new] paging
+#   @note
+#     This action accepts paging parameters:
+#     - *per_page* [Integer] - The maximum number of results to return per
+#       call (i.e. "page"). Max 1000.
+#     - *page* [Integer] - The page number to return for the request. 1-based.
+
 module Phaxio
-  include  HTTMultiParty
-  base_uri 'https://api.phaxio.com/v1'
+  # @api private
 
-  module Config
-    attr_accessor :api_key, :api_secret
-  end
+  class Client
+    class << self
+      # Makes a request to the Phaxio API.
+      #
+      # @param method [Symbol, String]
+      #   The HTTP method for the request. Currently only `:get`, `:post`, and `:delete` are
+      #   supported.
+      # @param endpoint [String]
+      #   The endpoint for the API action, relative to `Phaxio::Config.api_endpoint`.
+      # @param params [Hash]
+      #   Any parameters to be sent with the request.
+      #
+      # @return [Object]
+      #   The `"data"` attribute of the deserialized JSON response. Varies based on the API action.
+      def request method, endpoint, params = {}
+        params = api_params params
+        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."
+                     end
+          handle_response response
+        rescue Faraday::ConnectionFailed, Faraday::TimeoutError, Faraday::SSLError => error
+          raise Error::ApiConnectionError, "Error communicating with Phaxio: #{error}"
+        end
+      end
 
-  module Client
-    # Public: Send a fax.
-    #
-    # options - The Hash options used to refine the selection (default: {}):
-    #           :to                        - The Phone Number (i.e. [country
-    #                                        code][number] or just a 10 digit
-    #                                        number in the US or Canada). Put
-    #                                        square brackets after parameter
-    #                                        name to send to multiple
-    #                                        recipients (e.g. to[]) (required).
-    #           :filename                  - The Binary Stream name of the file
-    #                                        you want to fax. This is optional
-    #                                        if you specify string_data. Must
-    #                                        have file name in the filename
-    #                                        field of the body-part header. Put
-    #                                        square brackets after parameter
-    #                                        name to send multiple files (e.g.
-    #                                        filename[]) (required).
-    #           :string_data               - A String of html, plain text, or a
-    #                                        URL. If additional files are
-    #                                        specified as well, this data will
-    #                                        be included first in the fax
-    #                                        (optional).
-    #           :string_data_type          - An enum of the type of the string
-    #                                        data that can be 'html', 'url', or
-    #                                        'text'. If not specified, default
-    #                                        is 'text'. See string data
-    #                                        rendering for more info (optional).
-    #           :batch                     - The bool for running in batching
-    #                                        mode. If present and true, fax will
-    #                                        be sent in batching mode. Requires
-    #                                        batch_delay to be specified
-    #                                        (optional).
-    #           :batch_delay               - The int the of amount of time, in
-    #                                        seconds, before the batch is fired.
-    #                                        Must be specified if batch=true.
-    #                                        Maximum delay is 3600 (1 hour)
-    #                                        (optional).
-    #           :batch_collision_avoidance - The bool for collision avoidance
-    #                                        with batches. If true when
-    #                                        batch=true, fax will be blocked
-    #                                        until the receiving machine is no
-    #                                        longer busy (optional).
-    #           :callback_url              - The String url for the callback.
-    #                                        Overrides the globally set one
-    #                                        (optional).
-    #           :cancel_timeout            - An int of the number of minutes
-    #                                        after which the fax will be
-    #                                        canceled if it hasn't yet
-    #                                        completed. Must be between 1 and 60
-    #                                        (optional).
-    #
-    # Examples
-    #
-    #   Phaxio.send_fax(to: "0123456789", filename: "test.pdf")
-    #
-    # Returns a HTTParty::Response object containing a success bool,
-    # a String message, and an in faxID.
-    def send_fax(options)
-      send_post("/send", options)
-    end
+      # @return [Faraday::Connection] A new Faraday connection to `Phaxio::Config.api_endpoint`.
+      def conn
+        Faraday.new(Phaxio.api_endpoint) do |conn|
+          conn.request :multipart
+          conn.request :url_encoded
+          conn.adapter :net_http
 
-    # Public: Test receiving a fax.
-    #
-    # options - The Hash options used to refine the selection (default: {}):
-    #           from_number - The Phone Number of the simulated sender
-    #                         (optional).
-    #           to_number   - The Phone Number receiving the fax (optional).
-    #           filename    - A String containing the name of the PDF that has
-    #                         a PhaxCode and is the file you want to simulate
-    #                         sending (required).
-    #
-    # Examples
-    #
-    #   Phaxio.test_receive(filename: "test_file.pdf")
-    #
-    # Returns a HTTParty::Response object containing a success bool
-    # and a String message.
-    def test_receive(options)
-      send_post("/testReceive", options)
-    end
+          if Phaxio.api_key && Phaxio.api_secret
+            conn.basic_auth Phaxio.api_key, Phaxio.api_secret
+          end
+        end
+      end
 
-    # Public: Provision a phone number that you can use to receive faxes in
-    #         your Phaxio account.
-    #
-    # options - The Hash options used to refine the selection (default: {}):
-    #           area_code    - The integer area code of the number you'd like
-    #                          to provision (required).
-    #           callback_url - A callback URL that Phaxio will post to when a
-    #                          fax is received by this number. This will
-    #                          override the global receive callback URL, if you
-    #                          have one set (optional).
-    #
-    # Examples
-    #
-    #   Phaxio.provision_number(area_code: 802)
-    #
-    # Returns a HTTParty::Response object containing a success bool, a string
-    # message, and data containing the phone number, city, state, cost,
-    # last_billed_at, and the date the number was provisioned at.
-    def provision_number(options)
-      send_post("/provisionNumber", options)
-    end
+      private
 
-    # Public: Release a phone number that you no longer need. Once a phone
-    #         number is released you will no longer be charged for it.
-    #
-    # options - The Hash options used to refine the selection (default: {}):
-    #           number - The String of the phone number you want to release
-    #                    (required).
-    #
-    # Examples
-    #
-    #   Phaxio.release_number(number: "8021112222")
-    #
-    # Returns a HTTParty::Response object containing a success bool and a
-    # string message.
-    def release_number(options)
-      send_post("/releaseNumber", options)
-    end
+      def handle_response response
+        content_type = response.headers[:content_type]
 
-    # Public: Get a detailed list of the phone numbers you current own on
-    #         Phaxio.
-    #
-    # options - The Hash options used to refne th selection (default: {}):
-    #           area_code - An integer area code you'd like to filter by 
-    #                       (optional).
-    #           number    - A String phone number you'd like to retrieve
-    #                       (optional).
-    #
-    # Examples
-    #
-    #   Phaxio.list_numbers # list all the numbers you own
-    #
-    #   Phaxio.list_numbers(area_code: 802) # list all numbers in the 802 area
-    #
-    #   Phaxio.list_numbers(number: "8021112222") # show specific number detail
-    #
-    # Returns a HTTParty::Reponse object containing a success bool, a message,
-    # and the data attributes containing the queried phone number(s) details.
-    def list_numbers(options = {})
-      send_post("/numberList", options)
-    end
+        if content_type.start_with? 'application/json'
+          body = JSON.parse(response.body).with_indifferent_access
+        else
+          extension = MimeTypeHelper.extension_for_mimetype content_type
+          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
 
-    # Public: Get an image thumbnail or PDF file for a fax. For images to work
-    #         file storage must not be disabled with Phaxio.
-    #
-    # options - The Hash options used to refine the selection (default: {}):
-    #           id   - The integer fax id of the fax you wish to retreive
-    #                  (required).
-    #           type - An enum for the type return, defaults to 'p' (optional):
-    #                  s - Small JPG format thumbnail of the fax, 129 x 167 px.
-    #                  l - Large JPG format thumbnail of the fax, 300 x 388 px.
-    #                  p - PDF version of the fax (default).
-    #
-    # Examples
-    #
-    #   Phaxio.get_fax_file(id: 1234, type: p)
-    #   Phaxio.get_fax_file(id: 3254, type: l)
-    #
-    # Returns the fax as the type specified in the call, defaults to PDF.
-    def get_fax_file(options)
-      send_post("/faxFile", options)
-    end
+        if response.success?
+          raise(Error::GeneralError, body['message']) unless body['success']
 
-    # Public: List faxes within the specified time range.
-    #
-    # options - The Hash options used to refine the selection (default: {}):
-    #           start - The Unix Timestamp for the beginning of the range
-    #                   (required).
-    #           end   - The Unix Timestamp for the end of the range (required).
-    #
-    # Examples
-    #
-    #   Phaxio.list_faxes(start: 1293861600, end: 1294034400)
-    #
-    # Returns a HTTParty::Response object containing a success bool, a string
-    # message, paging information, and the fax data.
-    def list_faxes(options)
-      send_post("/faxList", options)
-    end
+          # Check if this is a response with paging. If so, we want to return that along with the
+          # data.
+          if body.key? 'paging'
+            {'data' => body['data'], 'paging' => body['paging']}
+          else
+            body['data']
+          end
+        else
+          status = response.status
+          # TODO: Handle blank message
+          message = body['message']
 
-    # Public: Get the status of a specific fax.
-    #
-    # options - The Hash options used to refine the selection (default: {}):
-    #           id - The int id of the fax you want to get the status of
-    #                (required).
-    #
-    # Examples
-    #
-    #   Phaxio.get_fax_status(id: "123456")
-    #
-    # Returns a HTTParty::Response object containing a success bool,
-    # a String message, and the data of the fax.
-    def get_fax_status(options)
-      if options[:id].nil?
-        raise StandardError, "You must include a fax id."
+          case status
+          when 401
+            raise Error::AuthenticationError, "#{status}: #{message}"
+          when 404
+            raise Error::NotFoundError, "#{status}: #{message}"
+          when 422
+            raise Error::InvalidRequestError, "#{status}: #{message}"
+          when 429
+            raise Error::RateLimitExceededError, "#{status}: #{message}"
+          else
+            raise Error::GeneralError, "#{status}: #{message}"
+          end
+        end
       end
 
-      send_post("/faxStatus", options)
-    end
+      def tmpname(extension)
+        t = Time.now.strftime("%Y%m%d")
+        "phaxio-#{t}-#{$$}-#{rand(0x100000000).to_s(36)}-download.#{extension}"
+      end
 
-    # Public: Cancel a specific fax.
-    #
-    # options - The Hash options used to refine the selection (defaults: {}):
-    #           id - The int id of the fax you want to cancel (required).
-    #
-    # Examples
-    #
-    #   Phaxio.cancel_fax(id: "123456")
-    #
-    # Returns a HTTParty::Response object containing a success bool
-    # and a String message.
-    def cancel_fax(options)
-      send_post("/faxCancel", options)
-    end
+      def post endpoint, params = {}
+        # Handle file params
+        params.each do |k, v|
+          next unless k.to_s == 'file'
 
-    # Public: Get the status of Client's account.
-    #
-    # Examples
-    #
-    #   Phaxio.get_account_status
-    #
-    # Returns a HTTParty::Response object with success, message, and data
-    # (containing faxes_sent_this_month, faxes_sent_today, and balance).
-    def get_account_status
-      send_post("/accountStatus", {})
-    end
+          if v.is_a? Array
+            file_param = v.map { |file| file_to_param file }
+          else
+            file_param = file_to_param v
+          end
 
-    def send_post(path, options)
-      post(path, query: options.merge!({api_key: api_key, api_secret: api_secret}))
-    end
-  end
+          params[k] = file_param
+        end
 
-  # Public: Configure Phaxio with your api_key and api_secret
-  #
-  # Examples
-  #
-  #   Phaxio.config do |config|
-  #      config.api_key = "12345678910"
-  #      config.api_secret = "10987654321"
-  #    end
-  #
-  # Returns nothing.
-  def self.config
-    yield(self)
-  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.patch endpoint, params, api_headers(params)
+      end
+
+      def get endpoint, params = {}
+        conn.get endpoint, params, api_headers(params)
+      end
+
+      def delete endpoint, params = {}
+        conn.delete endpoint, params, api_headers(params)
+      end
+
+      def api_params params
+        # Convert times to ISO 8601
+        params.each do |k, v|
+          next unless v.kind_of?(Time) || v.kind_of?(Date)
+          params[k] = v.to_datetime.iso8601
+        end
 
-  extend Client
-  extend Config
+        params
+      end
+
+      def api_headers params
+        api_key    = params[:api_key]    || Phaxio.api_key
+        api_secret = params[: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
 end

data/lib/phaxio/config.rb

@@ -0,0 +1,31 @@
+module Phaxio
+  class Config
+    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.
+      #
+      # 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