rev-api 1.0.0

data/lib/rev-api.rb

@@ -0,0 +1,26 @@
+require 'httparty'
+
+# These three are the only classes that should be accessed directly
+require 'rev-api/api'
+
+module Rev 
+  class << self
+    # Alias for Rev::Api.new
+    #
+    # @return [Rev::Api]
+    def new(client_api_key, user_api_key, host)
+      Rev::Api.new(client_api_key, user_api_key, host)
+    end
+
+    # Delegate to Rev::Api
+    #
+    def method_missing(method, *args, &block)
+      return super unless new.respond_to?(method)
+      new.send(method, *args, &block)
+    end
+
+    def respond_to?(method, include_private = false)
+      new.respond_to?(method, include_private) || super(method, include_private)
+    end
+  end
+end

data/lib/rev-api/api.rb

@@ -0,0 +1,311 @@
+require 'rev-api/version'
+require 'rev-api/http_client'
+require 'rev-api/exceptions'
+require 'json'
+
+# automatically include business logic objects
+Dir[File.dirname(__FILE__) + '/models/*.rb'].each do |file|
+  require file
+end
+
+# Rev API Ruby SDK
+module Rev
+  # Main point of interaction with API.
+  # Wraps common REST operations, returning plain objects.
+  # Internally utilizes JSON resource representation.
+  class Api
+
+    # Production host. Used by default for new Rev::Api client
+    PRODUCTION_HOST = 'www.rev.com'
+
+    # Sandbox domain - pass 'Rev::Api::SANDBOX_HOST' as third param
+    # into Rev::Api ctor
+    SANDBOX_HOST = 'api-sandbox.rev.com'
+
+    # @note http://www.rev.com/api/security
+    # @param client_api_key [String] secret key specific to each partner that wishes to use the Rev API
+    # @param user_api_key [String] secret key specific to a Rev user, which identifies the user account under whose privileges the requested operation executes
+    # @param host [String] use {Rev::Api::PRODUCTION_HOST} or {Rev::Api::SANDBOX_HOST}. Production is default value
+    # @return [HttpClient] client obj
+    def initialize(client_api_key, user_api_key, host = PRODUCTION_HOST)
+      @client = HttpClient.new(client_api_key, user_api_key, host)
+    end
+
+    # Loads single page of existing orders for current client
+    #
+    # @note http://www.rev.com/api/ordersget
+    # @param page [Int, nil] 0-based page number, defaults to 0
+    # @return [OrdersListPage] paged result cointaining 'orders'
+    def get_orders_page(page = 0)
+      response = @client.get("/orders?page=#{page.to_i}")
+      Api.verify_get_response(response)
+      OrdersListPage.new(Api.parse(response))
+    end
+
+    # Loads all orders for current client. Works by calling get_orders_page multiple times.
+    # Use with caution if your order list might be large.
+    #
+    # @note http://www.rev.com/api/ordersget
+    # @return [Array of Order] list of orders
+    def get_all_orders
+      orders = []
+      page = 0
+      loop do
+        orders_page = self.get_orders_page page
+        page += 1
+        orders.push *orders_page.orders
+        break if (page * orders_page.results_per_page >= orders_page.total_count)
+      end
+      orders
+    end
+
+    # Returns Order given an order number.
+    #
+    # @note http://www.rev.com/api/ordersgetone
+    # @param number [String] order number, like 'TCXXXXXXXX'
+    # @return [Order] order obj
+    def get_order(number)
+      response = @client.get("/orders/#{number}")
+      Api.verify_get_response(response)
+      Order.new(Api.parse(response))
+    end
+
+    # Cancel an order by number. If cancellation is not allowed, Rev::Api::BadRequestError is raised.
+    #
+    # @note http://www.rev.com/api/orderscancel
+    # @param number [String] order number
+    # @return [Boolean] true on success, raised Exception from Rev::Api namespace otherwise
+    def cancel_order(number)
+      data = { :order_num => number }
+      response = @client.post("/orders/#{number}/cancel", data)
+      Api.verify_post_response(response)
+    end
+
+    # Get metadata about an order attachment.
+    # Use this method to retrieve information about an order attachment (either transcript,
+    # translation, or source file).
+    #
+    # @note http://www.rev.com/api/attachmentsget
+    # @param id [String] attachment id, as returned in info about an order
+    # @return [Attachment] attachment object
+    def get_attachment_metadata(id)
+      response = @client.get("/attachments/#{id}")
+      Api.verify_get_response(response)
+      Attachment.new(Api.parse(response))
+    end
+
+    # Get the raw data for the attachment with given id.
+    # Download the contents of an attachment. Use this method to download either a finished transcript,
+    # finished translation or a source file for an order.
+    # For transcript and translation attachments, you may request to get the contents in a specific
+    # representation, specified via a mime-type.
+    #
+    # See {Rev::Order::Attachment::REPRESENTATIONS} hash, which contains symbols for currently supported mime types.
+    # The authoritative list is in the API documentation at http://www.rev.com/api/attachmentsgetcontent
+    #
+    # If a block is given, the response is passed to the block directly, to allow progressive reading of the data.
+    # In this case, the block must itself check for error responses, using Api.verify_get_response.
+    # If no block is given, the full response is returned. In that case, if the response is an error, an appropriate
+    # error is raised.
+    #
+    # @param id [String] attachment id
+    # @param mime_type [String, nil] mime-type for the desired format in which the content should be retrieved.
+    # @yieldparam resp [Net::HTTP::Response] the response, ready to be read
+    # @return [Net::HTTP::Response] the response containing raw data
+    def get_attachment_content(id, mime_type = nil, &block)
+      headers = {}
+
+      unless mime_type.nil?
+        headers['Accept'] = mime_type
+        headers['Accept-Charset'] = 'utf-8' if mime_type.start_with? 'text/'
+      end
+
+      if block_given?
+        @client.get_binary("/attachments/#{id}/content", headers, &block)
+      else
+        response = @client.get_binary("/attachments/#{id}/content", headers)
+        Api.verify_get_response(response)
+        response
+      end
+    end
+
+    # Get the raw data for the attachment with given id.
+    # Download the contents of an attachment and save it into a file. Use this method to download either a finished transcript,
+    # finished translation or a source file for an order.
+    # For transcript and translation attachments, you may request to get the contents in a specific
+    # representation, specified via a mime-type.
+    #
+    # See {Rev::Order::Attachment::REPRESENTATIONS} hash, which contains symbols for currently supported mime types.
+    # The authoritative list is in the API documentation at http://www.rev.com/api/attachmentsgetcontent
+    #
+    # @param id [String] attachment id
+    # @param path [String, nil] path to file into which the content is to be saved.
+    # @param mime_type [String, nil] mime-type for the desired format in which the content should be retrieved.
+    # @return [String] filepath content has been saved to. Might raise standard IO exception if file creation files
+    def save_attachment_content(id, path, mime_type = nil)
+      headers = {}
+
+      unless mime_type.nil?
+        headers['Accept'] = mime_type
+        headers['Accept-Charset'] = 'utf-8' if mime_type.start_with? 'text/'
+      end
+
+      # same simple approach as box-api does for now: return response.body as-is if path for saving is nil
+      File.open(path, 'wb') do |file|
+        response = @client.get_binary("/attachments/#{id}/content", headers) do |resp|
+          resp.read_body do |segment|
+            file.write(segment)
+          end
+        end
+        Api.verify_get_response(response)
+      end
+
+      # we don't handle IO-related exceptions
+      path
+    end
+
+    # Get the content of the attachment with given id as a string. Use this method to grab the contents of a finished transcript
+    # or translation as a string. This method should generally not be used for source attachments, as those are typically
+    # binary files like MP3s, which cannot be converted to a string.
+    #
+    # May raise Rev::Api::NotAcceptableError if the attachment cannot be converted into a text representation.
+    #
+    # @param id [String] attachment id
+    # @return [String] the content of the attachment as a string
+    def get_attachment_content_as_string(id)
+      response = self.get_attachment_content(id, Attachment::REPRESENTATIONS[:txt])
+      response.body
+    end
+
+    # Submit a new order using {Rev::OrderRequest}.
+    # @note http://www.rev.com/api/ordersposttranscription - for full information
+    #
+    # @param order_request [OrderRequest] object specifying payment, inputs, options and notification info.
+    #        inputs must previously be uploaded using upload_input or create_input_from_link
+    # @return [String] order number for the new order
+    #         Raises {Rev::BadRequestError} on failure (.code attr exposes API error code -
+    #         see {Rev::OrderRequestError}).
+    def submit_order(order_request)
+      response = @client.post("/orders", order_request.to_json, { 'Content-Type' => 'application/json' })
+      Api.verify_post_response(response)
+
+      new_order_uri = response.headers['Location']
+      return new_order_uri.split('/')[-1]
+    end
+
+    # Upload given local file directly as source input for order.
+    # @note http://www.rev.com/api/inputspost
+    #
+    # @param path [String] mandatory, path to local file (relative or absolute) to upload
+    # @param content_type [String] mandatory, content-type of the file you're uploading
+    # @return [String] URI identifying newly uploaded media. This URI can be used to identify the input
+    #         when constructing a OrderRequest object to submit an order.
+    #         {Rev::BadRequestError} is raised on failure (.code attr exposes API error code -
+    #         see {Rev::InputRequestError}).
+    def upload_input(path, content_type)
+      filename = Pathname.new(path).basename
+      headers = {
+        'Content-Disposition' => "attachment; filename=#{filename}",
+        'Content-Type' => content_type
+      }
+
+      File.open(path) do |data|
+        response = @client.post_binary("/inputs", data, headers)
+        Api.verify_post_response(response)
+
+        headers = HTTParty::Response::Headers.new(response.to_hash)
+        return headers['Location']
+      end
+    end
+
+    # Request creation of a source input based on an external URL which the server will attempt to download.
+    # @note http://www.rev.com/api/inputspost
+    #
+    # @param url [String] mandatory, URL where the media can be retrieved. Must be publicly accessible.
+    #        HTTPS urls are ok as long as the site in question has a valid certificate
+    # @param filename [String, nil] optional, the filename for the media. If not specified, we will
+    #        determine it from the URL
+    # @param content_type [String, nil] optional, the content type of the media to be retrieved.
+    #        If not specified, we will try to determine it from the server response
+    # @return [String] URI identifying newly uploaded media. This URI can be used to identify the input
+    #         when constructing a OrderRequest object to submit an order.
+    #         {Rev::BadRequestError} is raised on failure (.code attr exposes API error code -
+    #         see {Rev::InputRequestError}).
+    def create_input_from_link(url, filename = nil, content_type = nil)
+      request = { :url => url }
+      request[:filename] = filename unless filename.nil?
+      request[:content_type] = content_type unless content_type.nil?
+
+      response = @client.post("/inputs", request.to_json, { 'Content-Type' => 'application/json' })
+      Api.verify_post_response(response)
+
+      response.headers['Location']
+    end
+
+  private
+    # Below are utility helper methods for handling response
+    class << self
+
+      # Parse given response's body JSON into Hash, so that it might be
+      # easily mapped onto business logic object.
+      #
+      # @param response [Response] HTTParty response obj
+      # @return [Hash] hash of values parsed from JSON
+      def parse(response)
+        JSON.load response.body.to_s
+      end
+
+      # Raises exception if response is not considered as success
+      #
+      # @param response [HTTPParty::Response] HTTParty response obj. Net::HTTPResponse represented by .response
+      # @return [Boolean] true if response is considered as successful
+      def verify_get_response(response)
+        # HTTP response codes are handled here and propagated up to the caller, since caller should be able
+        # to handle all types of errors the same - using exceptions
+        unless response.response.instance_of? Net::HTTPOK
+          Api.handle_error(response)
+        end
+
+        true
+      end
+
+      # (see #verify_get_response)
+      def verify_post_response(response)
+        # see http://www.rev.com/api/errorhandling
+        unless response.response.instance_of?(Net::HTTPCreated) || response.response.instance_of?(Net::HTTPNoContent)
+          Api.handle_error(response)
+        end
+
+        true
+      end
+
+      # Given a response, raises a corresponding Exception.
+      # Full response is given for the sake of BadRequest reporting,
+      # which usually contains validation errors.
+      #
+      # @param response [Response] containing failing status to look for
+      def handle_error(response)
+        case response.response
+          when Net::HTTPBadRequest
+            # Bad request - response contains error code and details. Usually means failed validation
+            body = JSON.load response.body.to_s
+            msg = "API responded with code #{body['code']}: #{body['message']}"
+            msg += " Details: #{body['detail'].to_s}" if body['detail']
+            raise BadRequestError.new msg, body['code']
+          when Net::HTTPUnauthorized
+            raise NotAuthorizedError
+          when Net::HTTPForbidden
+            raise ForbiddenError
+          when Net::HTTPNotFound
+            raise NotFoundError
+          when Net::HTTPNotAcceptable
+            raise NotAcceptableError
+          when Net::HTTPServerError
+            raise ServerError, "Status code: #{response.code}"
+          else
+            raise UnknownError
+        end
+      end
+    end
+  end
+end

data/lib/rev-api/api_serializable.rb

@@ -0,0 +1,30 @@
+module Rev
+  # Utility class with instance methods for hash/JSON conversion
+  class ApiSerializable
+
+    # Map given hash to instance properties
+    #
+    # @param fields [Hash] of fields to initialize instance. See instance attributes for available fields.
+    def initialize(fields = {})
+      fields.each { |k,v| self.instance_variable_set("@#{k.to_sym}", v) if self.methods.include? k.to_sym }
+    end
+
+    # Recursively convert object to hash
+    # @note http://stackoverflow.com/questions/1684588/how-to-do-ruby-object-serialization-using-json
+    #
+    # @return [Hash] hash map of the object including all nested children
+    def to_hash
+      h = {}
+      instance_variables.each do |e|
+        o = instance_variable_get e.to_sym
+        h[e[1..-1]] = (o.respond_to? :to_hash) ? o.to_hash : o;
+      end
+      h
+    end
+
+    # Recursively convert object to JSON (internally utilizing hash)
+    def to_json *args
+      to_hash.to_json *args
+    end
+  end
+end

data/lib/rev-api/exceptions.rb

@@ -0,0 +1,108 @@
+module Rev
+  class ApiError < StandardError; end
+
+  # 400 BadRequest. Response body contains API error code and optional details
+  class BadRequestError < ApiError
+
+    # Code of the validation error
+    attr_reader :code
+
+    # @param message [String] custom message, usually includes API validation error code and it's meaning
+    # @param code [Integer] API validation code is passed separately to be evaluated in consumer's app
+    def initialize(message, code)
+      super message
+      @code = code
+    end
+  end
+
+  # 401 Unauthorized
+  class NotAuthorizedError < ApiError; end
+
+  # 403 Forbidden (not allowed)
+  class ForbiddenError < ApiError; end
+
+  # 404 Not Found
+  class NotFoundError < ApiError; end
+
+  # 406 NotAcceptable (used when requested representation is not supported by attachment)
+  class NotAcceptableError < ApiError; end
+
+  # 500 ServerError (internal error on API server)
+  class ServerError < ApiError; end
+
+  # have no idea what's going on - used in 'pokemon' rescue
+  class UnknownError < ApiError; end
+
+  # Constants for validation error codes in OrderRequest response
+  module OrderRequestErrorCodes
+    # 10001 Missing Inputs - if the order request did not contain any input media
+    MISSING_INPUTS = 10001
+
+    # 10002 Invalid Input - if one of the input media URIs is invalid, eg does not identify a valid media uploaded via a POST to /inputs
+    INVALID_INPUTS = 10002
+
+    # 10003 Transcription and Translation Specified - only one of the translation option and transcription option sections can be included
+    TC_AND_TR_OPTIONS_SPECIFIED = 10003
+
+    # 10001 Missing Inputs - if the order request did not contain any input media
+    TC_OR_TR_OPTIONS_NOT_SPECIFIED = 10004
+
+    # 10005 External Link and URI specified - only External Link or URI should be set for input media
+    EXTERNAL_LINK_AND_URI_SPECIFIED = 10005
+
+    # 10006 Input Location is not specified - neither of External Link and URI set for input media
+    EXTERNAL_LINK_OR_URI_NOT_SPECIFIED = 10006
+
+    # 20001 Invalid Audio Length - If one of the input medias has a specified length that is not a positive integer
+    INVALID_AUDIO_LENGTH = 20001
+
+    # 20002 Invalid Word Count - word counts for translation are missing or inaccurate
+    INVALID_WORD_COUNT = 20002
+
+    # 20003 Invalid Language Code - the language codes provided for translation are invalid
+    INVALID_LANGUAGE_CODE = 20003
+
+    # 20010 Reference Number Too Long Code - the reference number provided longer than 40 characters
+    REFERENCE_NUMBER_TOO_LONG = 20010
+
+    # 30001 Missing Payment Info - if the order request did not contain a payment information element
+    MISSING_PAYMENT_INFO = 30001
+
+    # 30002 Missing Payment Type - if the order request did not contain a payment kind element
+    MISSING_PAYMENT_TYPE = 30002
+
+    # 30010 Ineligible For Balance Payments - if the user on whose behalf the order request was made is not eligible for paying using account balance
+    INELIGIBLE_FOR_BALANCE_PAYMENT = 30010
+
+    # 30011 Account Balance Limit Exceeded - if the order request specified payment using account balance, but doing so would exceed the user's balance limit
+    ACCOUNT_BALANCE_LIMIT_EXCEEDED = 30011
+
+    # 30020 Missing Credit Card Info - if the order request specified payment using credit card, but did not provide the credit card info element
+    MISSING_CREDIT_CARD_INFO = 30020
+
+    # 30021 Invalid Saved Credit Card - if the order request specified payment using a saved credit card, but the specified credit card id was invalid
+    INVALID_SAVED_CREDIT_CARD = 30021
+
+    # 30023 Invalid Credit Card Details - if the order request specified payment using credit card, but some required credit card data elements were missing or had invalid values
+    INVALID_CREDIT_CARD_DETAILS = 30023
+
+    # 30024 Credit Card Authorization Failed - if the order request specified payment using credit card, but we could not charge the card
+    CREDIT_CARD_AUTHORIZATION_FAILED = 30024
+  end
+
+  module InputRequestErrorCodes
+    # 10001 Unsupported Content Type – if the content type of the media is not currently supported by our system.
+    # Supported media types for inputs are listed in http://www.rev.com/api/inputspost
+    UNSUPPORTED_CONTENT_TYPE = 10001
+
+    # 10002 Could not retrieve file – if we could not retrieve the file from the specified location.
+    COULD_NOT_RETRIEVE_MEDIA = 10002
+
+    # 10003 Invalid multipart request – If the multipart request did not contain exactly one file part, or was otherwise malformed.
+    INVALID_MULTIPART_REQUEST = 10003
+
+    # 10004 Unspecified filename - If the filename for the media was not specified explicitly and could not be determined automatically.
+    UNSPECIFIED_FILENAME = 10004
+  end
+
+end