rev-api 1.0.0

data/lib/rev-api/http_client.rb

@@ -0,0 +1,97 @@
+module Rev
+
+  # HTTP client handling authentication and HTTP requests at the low level for the Api class.
+  # Not indended to be used directly - clients should be using the Api class instead.
+  class HttpClient
+
+    include HTTParty
+
+    USER_AGENT = "RevOfficialRubySDK/#{VERSION}"
+
+    # Create a new HttpClient, connecting to given host, and using the given Client and User API Keys.
+    #
+    # @param client_api_key [String] the client API key to use for authenticating
+    # @param user_api_key [String] the user API key to use for authenticating
+    # @param host [String] the host to send requests to. Should be one of Rev::Api::PRODCUTION_HOST or Rev::Api::SANDBOX_HOST
+    def initialize(client_api_key, user_api_key, host)
+      endpoint_uri = "https://#{host}/api/v1"
+      self.class.base_uri(endpoint_uri)
+
+      auth_string = "Rev #{client_api_key}:#{user_api_key}"
+      @default_headers = {
+        'Authorization' => auth_string,
+        'User-Agent' => USER_AGENT # to track usage of SDK
+      }
+    end
+
+    # Performs HTTP GET of JSON data.
+    #
+    # @param operation [String] URL suffix describing specific operation, like '/orders'
+    # @param headers [Hash] hash of headers to use for the request
+    # @return [HTTParty::Response] response
+    def get(operation, headers = {})
+      headers = @default_headers.merge(headers)
+      self.class.get(operation, :headers => headers)
+    end
+
+    # Performs HTTP GET of binary data. Note, unlike post, this returns a
+    # Net::HTTP::Response, not HTTParty::Response.
+    #
+    # If this method is passed a block, will pass response to that block. in that case the response is not yet
+    # read into memory, so the block can read it progressively. otherwise, returns the response.
+    #
+    # @param operation [String] URL suffix describing specific operation, like '/orders'
+    # @param headers [Hash] hash of headers to use for the request
+    # @yieldparam resp [Net::HTTP::Response] the response, ready to be read
+    # @return [Net::HTTP::Response] response
+    def get_binary(operation, headers = {}, &block)
+      uri = URI.parse("#{self.class.base_uri}#{operation}")
+      headers = @default_headers.merge(headers)
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+
+      get = Net::HTTP::Get.new(uri.request_uri, headers)
+      if block_given?
+        http.request(get) do |resp|
+          yield resp
+        end
+      else
+        http.request(get)
+      end
+    end
+
+    # Performs HTTP POST of JSON data.
+    #
+    # @param operation[String] URL suffix describing specific operation
+    # @param data [Hash] hash of keys/values to post in request body
+    # @param headers [Hash] hash of headers to use for the request
+    # @return [HTTParty::Response] response
+    def post(operation, data = {}, headers = {})
+      headers = @default_headers.merge(headers)
+      self.class.post(operation, :headers => headers, :body => data)
+    end
+
+
+    # Performs HTTP POST of binary data. Note, unlike post, this returns a
+    # Net::HTTP::Response, not HTTParty::Response.
+    #
+    # @param operation[String] URL suffix describing specific operation
+    # @param file [File] file-like object containing the data to post
+    # @param headers [Hash] hash of headers to use for the request
+    # @return [Net::HTTP::Response] response
+    def post_binary(operation, file, headers = {})
+      uri = URI.parse("#{self.class.base_uri}#{operation}")
+      headers = @default_headers.merge(headers)
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+
+      post = Net::HTTP::Post.new(uri.request_uri, headers)
+      post["Content-Length"] = file.stat.size.to_s
+      post.body_stream = file
+
+      response = http.request(post)
+    end
+  end
+end

data/lib/rev-api/models/order.rb

@@ -0,0 +1,113 @@
+require 'rev-api/api_serializable'
+
+module Rev
+  # Represents Translation or Transcription order.
+  # Should have TranslationInfo or TranscriptionInfo, list
+  # of comments and attachments. Attributes names reflect
+  # API exposed names, but occasional hyphens are replaced
+  # with underscores
+  class Order < ApiSerializable
+    attr_reader :order_number, :price, :status, :attachments, :comments,
+      :translation, :transcription, :client_ref
+
+    # @param fields [Hash] hash of order fields parsed from JSON API response
+    def initialize(fields)
+      super fields
+      @attachments = fields['attachments'].map { |attachment_fields| Attachment.new(attachment_fields) }
+      @comments = fields['comments'].map { |comment_fields| Comment.new(comment_fields) }
+      @translation = TranslationInfo.new(fields['translation']) if fields['translation']
+      @transcription = TranscriptionInfo.new(fields['transcription']) if fields['transcription']
+    end
+
+    # @return [Array of Attachment] with the kind of "transcript"
+    def transcripts
+      @attachments.select { |a| a.kind == Attachment::KINDS[:transcript]}
+    end
+
+    # @return [Array of Attachment] with the kind of "translation"
+    def translations
+      @attachments.select { |a| a.kind == Attachment::KINDS[:translation]}
+    end
+
+    # @return [Array of Attachment] with the kind of "sources"
+    def sources
+      @attachments.select { |a| a.kind == Attachment::KINDS[:media]}
+    end
+  end
+
+  # Order comment, containing author, creation timestamp and text
+  class Comment < ApiSerializable
+    require 'date'
+
+    attr_reader :by, :timestamp, :text
+
+    # @param fields [Hash] hash of comment fields parsed from JSON API response
+    def initialize(fields)
+      super fields
+      @timestamp = Date.iso8601(fields['timestamp'])
+      @text = fields['text'] ? fields['text'] : String.new # right now API gives no 'text' field if text is empty
+    end
+  end
+
+  # Additional information specific to translation orders,
+  # such as word count, languages
+  class TranslationInfo < ApiSerializable
+    attr_reader :total_word_count, :source_language_code,
+      :destination_language_code
+  end
+
+  # Additional information specific to transcription orders,
+  # such as total length in minutes, verbatim and timestamps flags
+  class TranscriptionInfo < ApiSerializable
+    attr_reader :total_length, :verbatim, :timestamps
+  end
+
+  # Represents order attachment - logical document associated with order
+  class Attachment < ApiSerializable
+    attr_reader :kind, :name, :id, :audio_length, :word_count, :links
+
+    KINDS = {
+      :transcript => 'transcript',
+      :translation => 'translation',
+      :media => 'media'
+    }
+
+    # List of supported mime-types used to request attachment's content
+    # within 'Accept' header
+    REPRESENTATIONS = {
+      :docx => 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+      :doc => 'application/msword',
+      :pdf => 'application/pdf',
+      :txt => 'text/plain',
+      :youtube => 'text/plain; format=youtube-transcript'
+    }
+
+    # @param fields [Hash] fields of attachment fields parsed from JSON API response
+    def initialize(fields)
+      super fields
+      @links = fields['links'].map { |link_fields| Link.new(link_fields) }
+    end
+
+    # @param ext [Symbol] extension
+    # @return [String] mime-type for requested extension
+    def self.representation_mime(ext)
+      REPRESENTATIONS[ext]
+    end
+  end
+
+  # Link to actual file represented by attachment
+  class Link < ApiSerializable
+    attr_reader :rel, :href, :content_type
+  end
+
+  # Represents a paginated list of orders, including padination info.
+  class OrdersListPage < ApiSerializable
+    attr_reader :total_count, :results_per_page, :page, :orders
+
+    # @param fields [Hash] hash of OrdersListPage fields parsed from JSON API response
+    def initialize(fields)
+      super fields
+      @orders = fields['orders'].map { |order_fields| Order.new(order_fields) }
+    end
+  end
+end

data/lib/rev-api/models/order_request.rb

@@ -0,0 +1,183 @@
+require 'rev-api/api_serializable'
+
+module Rev
+  # OrderRequest is used for constructing order 'spec' in consumer code and passing it into.
+  # It consists of three main elements: :payment, :transcription_options and :notification.
+  # You can also supply reference number and customer comment
+  #
+  # @note http://www.rev.com/api/ordersposttranscription, http://www.rev.com/api/ordersposttranslation
+  class OrderRequest < ApiSerializable
+    # see {Rev::Payment}
+    attr_reader :payment
+
+    # see {Rev::TranscriptionOptions}
+    attr_reader :transcription_options
+
+    # see {Rev::TranslationOptions}
+    attr_reader :translation_options
+
+    # see {Rev::Notification}
+    attr_reader :notification
+
+    # a reference number for the order meaningful for the client (optional)
+    attr_reader :client_ref
+
+    # a comment with any special messages about the order (optional)
+    attr_reader :comment
+
+    # @param payment [Payment] payment info
+    # @param fields [Hash] of fields to initialize instance. See instance attributes for available fields.
+    def initialize(payment, fields = {})
+      super fields
+      @payment = payment
+    end
+  end
+
+  # Payment Info. Payment can be done either by charging a credit card or by debiting the user's
+  # account balance. If using a credit card, then either the user's saved credit card can be used
+  # or credit card details provided.
+  #
+  # For credit card payments, if specifying the credit card details in the request, the required
+  # elements are the card number, cardholder name, expiration month and year, and billing zipcode.
+  # If using the user's saved card, you must currently specify the value "1" for the saved card id,
+  # as we currently only allow a single card to be saved for a user.
+  class Payment < ApiSerializable
+    attr_accessor :type, :credit_card
+
+    # use to correctly set payment type
+    TYPES = {
+      :credit_card => 'CreditCard',
+      :balance => 'AccountBalance'
+    }
+
+    CC_ON_FILE_ID = 1
+
+    # @param type [String] payment method
+    # @param credit_card [CreditCard] cc obj, if type is 'CreditCard'
+    def initialize(type, credit_card = nil)
+      @type = type
+      @credit_card = credit_card unless credit_card.nil?
+    end
+
+    class << self
+      def with_credit_card_on_file()
+        Payment::new(TYPES[:credit_card], CreditCard.new(:saved_id => CC_ON_FILE_ID))
+      end
+
+      def with_saved_credit_card(credit_card)
+        Payment::new(TYPES[:credit_card], credit_card)
+      end
+
+      def with_account_balance()
+        Payment::new(TYPES[:account_balance])
+      end        
+    end
+  end
+
+  # Billing address
+  class BillingAddress < ApiSerializable
+    attr_reader :street, :street2, :city, :state, :zip, :country_alpha2
+  end
+
+  # Credit Card
+  class CreditCard < ApiSerializable
+    attr_reader :number, :expiration_month, :expiration_year, :cardholder, :billing_address, :saved_id
+  end
+
+  # Transcription options. This section contains the input media that must be transferred to our servers
+  # using a POST to /inputs, and are referenced using the URIs returned by that call. We also support external links.
+  # Following points explain usage of inputs:
+  # - For each input, you must provide either uri or external_link, but not both. If both or neither is provided,
+  #   error is returned.
+  # - You should only provide an external_link if it links to page where the media can be found, rather than directly to
+  #   the media file, and that we will not attempt to do anything with the link when the API call is made.
+  #   This is in contrast to when you post to /inputs with a link to a media file - in that case we do download the file.
+  #   So the external_link should only be used when you can't link to the media file directly.
+  # - The external_link can contain anything you want, but if it's a YouTube link, we will attempt to determine the
+  #   duration of the video on that page.
+  # We also allow users of the api to specify if translation should be done using our Verbatim option (:verbatim => true)
+  # and to specify if Time stamps should be included (:timestamps => true).
+  class TranscriptionOptions < ApiSerializable
+    # Mandatory, contains list of media to transcribe. Must have at least one element.
+    attr_reader :inputs
+
+    # Optional, should we transcribe the provided files verbatim? If true,
+    # all filler words (i.e. umm, huh) will be included.
+    attr_reader :verbatim
+
+    # Optional, should we include timestamps?
+    attr_reader :timestamps
+
+    # @param inputs [Array] list of inputs
+    # @param info [Hash] of fields to initialize instance. May contain:
+    #        - :verbatim => true/false
+    #        - :timestams => true/false
+    def initialize(inputs, info = {})
+      super info
+      @inputs = inputs
+    end
+  end
+
+  # Translation options. This section contains the input media that must be transferred to our
+  # servers using a POST to /inputs, and are referenced using the URIs returned by that call.
+  # For each media, word count must be specified. The language code for the source and desitination
+  # languages must also be specified.
+  class TranslationOptions < ApiSerializable
+    # Mandatory, contains list of media to transcribe. Must have at least one element.
+    attr_reader :inputs
+
+    # Mandatory, source language code
+    attr_reader :source_language_code
+
+    # Mandatory, destination language code
+    attr_reader :destination_language_code
+
+    # @param inputs [Array] list of inputs
+    # @param info [Hash] of fields to initialize instance. May contain:
+    #        - :source_language_code
+    #        - :destination_language_code
+    # @note For language codes refer to http://www.loc.gov/standards/iso639-2/php/code_list.php
+    def initialize(inputs, info = {})
+      super(info)
+      @inputs = inputs
+    end
+  end
+
+  # Input for order (aka source file)
+  class Input < ApiSerializable
+    #  Mandatory when used with {Rev::OrderRequest::TranslationInfo}, length of document, in words
+    attr_reader :word_length
+
+    # Length of audio, in minutes (mandatory in case of inability to determine it automatically).
+    # Used within {Rev::OrderRequest::TranscriptionInfo}
+    attr_reader :audio_length
+
+    # Mandatory, URI of the media, as returned from the call to POST /inputs.
+    # :external_link might substitute :uri for Transcription.
+    attr_reader :uri
+
+    # External URL, if sources wasn't POSTed as input (YouTube, Vimeo, Dropbox, etc)
+    attr_reader :external_link
+  end
+
+  # Notification Info. Optionally you may request that an HTTP post be made to a url of your choice when the order enters
+  # a new status (eg being transcribed or reviewed) and when it is complete.
+  class Notification < ApiSerializable
+    attr_reader :url, :level
+
+    # Notification levels
+    LEVELS = {
+      :detailed => 'Detailed',
+      :final_only => 'FinalOnly'
+    }
+
+    # @param url [String] The url for notifications. Mandatory if the notifications element is used. Updates will be posted to this URL
+    # @param level [String] Optional, specifies which notifications are sent:
+    #        - :detailed - a notification is sent whenever the order is in a new status or has a new comment
+    #        - :final_only - (the default), notification is sent only when the order is complete
+    def initialize(url, level = nil)
+      @url = url
+      @level = level ? level : LEVEL[:final_only]
+    end
+  end
+end

data/lib/rev-api/version.rb

@@ -0,0 +1,3 @@
+module Rev
+  VERSION = '1.0.0'
+end

data/rev-api.gemspec

@@ -0,0 +1,33 @@
+require 'date'
+require File.dirname(__FILE__) + '/lib/rev-api/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'rev-api'
+  s.version     = Rev::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.required_ruby_version = '>= 1.9.3'
+  s.date        = Date.today.to_s
+  s.summary     = "Ruby wrapper for Rev.com API"
+  s.description = "Communicate with Rev.com API using plain Ruby objects without bothering about HTTP"
+  s.authors     = ["Rev.com, Inc"]
+  s.email       = 'api@rev.com'
+  s.homepage    = 'http://www.rev.com/api'
+  s.license     = 'Apache License 2.0'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = [ "lib", "spec" ]
+
+  s.add_runtime_dependency('httparty', '>= 0.11.0')
+
+  s.add_development_dependency('webmock', '~> 1.11.0')
+  s.add_development_dependency('vcr', '~> 2.5.0')
+  s.add_development_dependency('turn', '~> 0.9.6')
+  s.add_development_dependency('rake', '>= 10.1.0')
+  s.add_development_dependency('yard')
+  s.add_development_dependency('redcarpet')
+  s.add_development_dependency('rubygems-tasks')
+
+  s.has_rdoc = 'yard'
+end

data/spec/fixtures/api_cassettes/cancel_order.yml

@@ -0,0 +1,38 @@
+---
+http_interactions:
+- request:
+    method: post
+    uri: https://www.revtrunk.com/api/v1/orders/TC0166192942/cancel
+    body:
+      encoding: US-ASCII
+      string: order_num=TC0166192942
+    headers:
+      Authorization:
+      - Rev welcome:AAAAAu/YjZ3phXU5FsF35yIcgiA=
+      User-Agent:
+      - RevOfficialRubySDK/1.0.0
+  response:
+    status:
+      code: 204
+      message: No Content
+    headers:
+      Cache-Control:
+      - no-cache
+      Pragma:
+      - no-cache
+      Expires:
+      - '-1'
+      Server:
+      - Microsoft-IIS/7.5
+      X-Miniprofiler-Ids:
+      - ! '["6f3dca3a-b095-4332-889f-d1212487407c"]'
+      X-Powered-By:
+      - ASP.NET
+      Date:
+      - Thu, 12 Sep 2013 20:14:44 GMT
+    body:
+      encoding: US-ASCII
+      string: ''
+    http_version: 
+  recorded_at: Thu, 12 Sep 2013 20:14:44 GMT
+recorded_with: VCR 2.5.0