transcribeme 0.0.5.beta → 1.0.0.alpha

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d18167f14ce8f645d7f14e325cd349fea1b9b51e
-  data.tar.gz: 652690384aee25eefb17ac89fd80a960be137e8c
+  metadata.gz: 220bcd847b3e0b90afbbea5f779e59705c7952ea
+  data.tar.gz: c6e5d50a3297e6b5756bb5e8d0f0185a6d94b1dc
 SHA512:
-  metadata.gz: 01fab4ab2552a0fab7c778f9a71f11ba2dbce1670c621f58d6af6b7f951c2aad70c88c5c924a39668d03c83ea07b11e3317f3b428a9a33ad6bdf335e3ab799b2
-  data.tar.gz: 77adffb1e925a81b7505a7693c8e24b61d20a04496480ba20de0269a3be138c987c83d02c73d8d3b109f95ea4b20cdac66f1c9738e8ac02527e14bcf1c0f094d
+  metadata.gz: a3ef2f1b18f139220c0096da77af39089707c4544afdda70dd03e854bdd4e8a46302ca108e2435960333b2c5221a7e48c9989eacbe5c9d5942e17d93f8edbc23
+  data.tar.gz: 6526240aafff85c06311693037ad10f3b5a8a09d285652cb53886f53426ad2e444e1b97a6c83d223dacc0a441f29a2130112faa09e32bf0381cc5ad1dd8e1401

data/.gitignore

@@ -7,7 +7,8 @@
 Gemfile.lock
 InstalledFiles
 _yardoc
-coverage
+coverage/
+coverage/*
 doc/
 lib/bundler/man
 pkg

data/.rubocop.yml

@@ -0,0 +1,22 @@
+TrailingWhitespace:
+  Enabled: false
+
+LineLength:
+  Enabled: false
+
+StringLiterals:
+  Enabled: false
+
+EmptyLines:
+  Enabled: false
+
+AllCops:
+  Includes:
+    - Rakefile
+    - config.ru
+  Excludes:
+    - db/schema.rb
+    - db/migrate/**
+    - bin/**
+    - config/**
+    - script/**

data/.travis.yml

@@ -0,0 +1,8 @@
+language: ruby
+rvm:
+  - 2.0.0
+  - 1.9.3
+  - 1.9.2
+  - jruby-19mode
+  - rbx-19mode
+  - jruby-head

data/Gemfile

@@ -3,7 +3,12 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in transcribeme-api.gemspec
 gemspec
 
-
-group :development, :tools do
+group :development, :test do
   gem 'pry'
+  gem 'rubocop'
+  gem 'guard-rspec'
+  gem 'guard-yard'
+  gem 'guard-rubocop'
+  gem 'terminal-notifier-guard'
+  gem 'coveralls', require: false
 end

data/Guardfile

@@ -0,0 +1,35 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard :rspec do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+
+  # Rails example
+  watch(%r{^app/(.+)\.rb$})                           { |m| "spec/#{m[1]}_spec.rb" }
+  watch(%r{^app/(.*)(\.erb|\.haml)$})                 { |m| "spec/#{m[1]}#{m[2]}_spec.rb" }
+  watch(%r{^app/controllers/(.+)_(controller)\.rb$})  { |m| ["spec/routing/#{m[1]}_routing_spec.rb", "spec/#{m[2]}s/#{m[1]}_#{m[2]}_spec.rb", "spec/acceptance/#{m[1]}_spec.rb"] }
+  watch(%r{^spec/support/(.+)\.rb$})                  { "spec" }
+  watch('config/routes.rb')                           { "spec/routing" }
+  watch('app/controllers/application_controller.rb')  { "spec/controllers" }
+
+  # Capybara features specs
+  watch(%r{^app/views/(.+)/.*\.(erb|haml)$})          { |m| "spec/features/#{m[1]}_spec.rb" }
+
+  # Turnip features and steps
+  watch(%r{^spec/acceptance/(.+)\.feature$})
+  watch(%r{^spec/acceptance/steps/(.+)_steps\.rb$})   { |m| Dir[File.join("**/#{m[1]}.feature")][0] || 'spec/acceptance' }
+end
+
+
+guard :rubocop do
+  watch(%r{.+\.rb$})
+  watch(%r{(?:.+/)?\.rubocop\.yml$}) { |m| File.dirname(m[0]) }
+end
+
+guard 'yard' do
+  watch(%r{app/.+\.rb})
+  watch(%r{lib/.+\.rb})
+  watch(%r{ext/.+\.c})
+end

data/README.md

@@ -6,10 +6,19 @@
 [![Code Climate](https://codeclimate.com/github/tuttinator/transcribeme.png)](https://codeclimate.com/github/tuttinator/transcribeme)
 
 
-### THIS IS STILL IN BETA
+### Description
 
+This gem is a Ruby wrapper for the TranscribeMe SOAP API, built on Savon, and includes some extra dangly bits for uploading to Windows Azure Blob storage.
 
-This gem is a Ruby wrapper for the TranscribeMe SOAP API, built on Savon
+The DSL may change before 1.0.0 stable is released. 
+
+Changes from prior 1.0.0 include bringing the Ruby method names in line with the actual SOAP action names.
+
+This gem wants to make it easy for you. If you call the 'sign_in' method before initializing a session then we all know you meant to. We'll jump right in there and initialize it for you.
+
+## Prerequisites
+
+This gem relies on FFMPEG for determining the duration of audio (and video) files. The TranscribeMe SOAP API leaves it as the client's responsibility for determining the duration of files being uploaded.
 
 ## Installation
 
@@ -37,11 +46,31 @@ The documentation can be [browsed online](http://rubydoc.info/github/tuttinator/
 
 ## Roadmap
 
-- [ ] Write specs
-- [ ] Set up Travis-CI and document supported Ruby versions
-- [ ] Investigate Windows Azure Blob storage file upload
-- [ ] Document SOAP calls and error messages
-- [ ] Complete YARD documentation
+Version 1.0.0 stable
+
+- [   ] Write specs
+- [ x ] Set up Travis-CI and document supported Ruby versions
+- [ x ] Investigate Windows Azure Blob storage file upload
+- [ x ] Include Excon for Windows Azure Blob storage
+- [ x ] Base64 decrypt transcription results
+- [   ] Document SOAP calls and error messages
+- [   ] Complete YARD documentation
+- [   ] Include option (default)
+- [   ] Validations for GUIDs 
+- [   ] Exceptions for error handling (about 50%)
+- [   ] Modelling Recording objects, particularly better describing recording status
+
+Version 1.1.0
+
+- [   ] Create a CLI interface
+
+RubyMotion
+
+- [   ] A RubyMotion fork (transcribeme-motion), wrapped in BubbleWrap's HTTP DSL (watch this space)
+
+REST API Wrapper
+
+- [   ] A Sinatra RESTful wrapper around the SOAP operations for your own personal REST API middleman, with JSON-ic magic at your fingertips. JSON was always my favourite Argonaut.
 
 ## Contributing
 

data/Rakefile

@@ -1,7 +1,7 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new
 
-task :default => :spec
-task :test => :spec
+task default: :spec
+task test: :spec

data/lib/transcribeme.rb

@@ -1,37 +1,5 @@
-require 'transcribeme/version'
-
-module TranscribeMe
-  module API
-
-      WSDL = "http://transcribeme-api.cloudapp.net/PortalAPI.svc?wsdl=wsdl0"
-      ENDPOINT = "http://transcribeme-api.cloudapp.net/PortalAPI.svc"
-      NAMESPACE = "http://TranscribeMe.API.Web"
-      NAMESPACE_IDENTIFIER = :tns # any identifier can be used
-
-      SOAP_ENVELOPE = ["soapenv:Envelope", { "xmlns:soapenv" => "http://schemas.xmlsoap.org/soap/envelope/", "xmlns:#{NAMESPACE_IDENTIFIER}" => NAMESPACE }]
-
-      def self.construct_xml(soap_method, options = {})
-        Builder::XmlMarkup.new.tag!(*SOAP_ENVELOPE) do |xml|
-          xml.tag!("soapenv:Body") do |xml|
-            xml.tag!("#{NAMESPACE_IDENTIFIER}:#{soap_method}") do |xml|
-              options.each do |key, value|
-                xml.tag!("#{NAMESPACE_IDENTIFIER}:#{key}") { |xml| xml.text! value }
-              end
-            end
-          end
-        end
-      end
-    
-  end
-end
-
 require 'savon'
-
-require 'transcribeme/api/client'
-require 'transcribeme/api/customer_login'
-require 'transcribeme/api/session'
-require 'transcribeme/api/recordings'
-require 'transcribeme/api/submission'
-require 'transcribeme/api/submission_with_promocode'
-require 'transcribeme/api/check_transcription_ready'
-require 'transcribeme/api/upload_url'
+require 'streamio-ffmpeg'
+require 'excon'
+require 'transcribeme/version'
+require 'transcribeme/api/client'

data/lib/transcribeme/api/client.rb

@@ -1,16 +1,34 @@
+# TranscribeMe
 module TranscribeMe
+  # API module
   module API
-
+    # API Client with methods for interacting with the SOAP API
     class Client
 
-      attr_accessor :session_id
-      attr_reader :savon, :session_expiry_time
-      
+      # Public: Returns the session id of the current session
+      attr_reader :session_id
+      # Public: Returns the expiry time of the current session
+      attr_reader :session_expiry_time
+      # Public: Returns the underlining Savon object
+      attr_reader :savon
+
+      WSDL = 'http://transcribeme-api.cloudapp.net/PortalAPI.svc?wsdl=wsdl0'
+      ENDPOINT = 'http://transcribeme-api.cloudapp.net/PortalAPI.svc'
+      NAMESPACE = 'http://TranscribeMe.API.Web'
+
+      # Public: Initializes the API Client class
+      #
       def initialize
-        @savon = ::Savon.client(wsdl: WSDL, endpoint: ENDPOINT, namespace: NAMESPACE, soap_version: 1)
+        # Note: Deliberately disabling the verbose Savon logging
+        @savon = ::Savon.client(endpoint: ENDPOINT,  namespace: NAMESPACE,
+                                soap_version: 1, wsdl: WSDL, log: false)
       end
 
-      def initialize_session!
+      # Public: Initializes a session on the API server and stores 
+      # the expiry time and the session_id in instance variables
+      #
+      # Returns the session_id GUID
+      def initialize_session
         response = @savon.call :initialize_session
         # Without ActiveSupport
         #   1.hour.from_now is 3600 seconds from Time.now
@@ -18,69 +36,201 @@ module TranscribeMe
         @session_id = response.body[:initialize_session_response][:initialize_session_result]
       end
 
-      def login_with(username, password)
+      # Public: Calls the 'SignIn' SOAP action
+      #
+      # username - a String which corresponds to a TranscribeMe Portal 
+      #            account username which can be any valid email address
+      # password - a String which is the portal account password
+      #
+      # Returns a GUID of the Customer ID
+      def sign_in(username, password)
         
-        initialize_session! unless session_valid?
+        # If #login_with is called before we have a session_id instance variable
+        # then call initialize_session
+        initialize_session unless session_valid?
 
+        # Use Savon to call the 'SignIn' SOAP action
         response = @savon.call  :sign_in, 
-                                message: {  "wsdl:sessionID"  => @session_id, 
-                                            "wsdl:username"   =>  username, 
-                                            "wsdl:password"   =>  password }
+                                message: {  'wsdl:sessionID'  => @session_id, 
+                                            'wsdl:username'   =>  username, 
+                                            'wsdl:password'   =>  password }
 
-        @customer_login_id = response.body[:sign_in_response][:sign_in_result]
+        error_message = response.body[:sign_in_response][:error_message]
+
+        raise error_message if error_message
 
+        # Assign the customer_login_id variable to the string in the SOAP response
+        @customer_login_id = response.body[:sign_in_response][:sign_in_result]
       end
 
+      # Public: Calls the 'GetCustomerRecordings' SOAP Action
+      #
+      # requires the user to be logged in
+      #
+      # Returns an Array of Hashes of with the properties of recording objects
       def get_recordings
-        # raise "Login first!" unless @customer_login_id
+        # raise 'Login first!' unless @customer_login_id
 
         response = @savon.call  :get_customer_recordings, 
-                                message: {  "wsdl:sessionID" => session_id }
+                                message: {  'wsdl:sessionID' => session_id }
 
         @recordings = response.body[:get_customer_recordings_response][:get_customer_recordings_result][:recording_info]                                
       end
 
+      # Public: Calls the 'GetUploadUrl' SOAP Action
+      #
+      # Returns the upload url as a String
       def get_upload_url
-        # raise "Login first!" unless @customer_login_id
+        # raise 'Login first!' unless @customer_login_id
 
         response = @savon.call  :get_upload_url, 
-                                message: {  "wsdl:sessionID" => @session_id }
+                                message: {  'wsdl:sessionID' => @session_id }
                                 
         @upload_url = response.body[:get_upload_url_response][:get_upload_url_result] 
+      end
 
+      # Public: uploads to Azure Blob Storage and commits the upload to
+      # the TranscribeMe SOAP API
+      #
+      # file_path - a String with the path to the actual file
+      # options   - a Hash with these keys:
+      #             :multiple_speakers  - Boolean (default is true)
+      #             :duration           - Float
+      #             :description        - String
+      #
+      # Returns the response as a Hash
+      def upload(file_path, options = {})
+
+        # If not logged in, raise this exception
+        raise 'Login first!' unless @customer_login_id
+
+        # Extract options from the options hash
+        multiple_speakers = options[:multiple_speakers] || true
+        description       = options[:description]
+        file_name         = File.basename(file_path)
+        file_format       = File.extname(file_path)
+        file_size         = File.stat(file_path).size
+        # Use the duration if provided in the options hash
+        duration          = options[:duration] || ::FFMPEG::Movie.new(file_path).duration
+
+        # Use the last upload url, or grab a new one
+        @upload_url ||= get_upload_url
+
+        # Create a connection to the upload url
+        connection = Excon.new(@upload_url)
+        # Upload to 
+        connection.put(headers: { "x-ms-blob-type" => "BlockBlob", 
+                                  "x-ms-date" => Time.now.to_s, 
+                                  "Content-Length" => file_size}, body: File.read(file_path))
+
+        # Post to the 
+        response = @savon.call :commit_upload, message: { "wsdl:sessionID"  => @session_id, 
+                                                          "wsdl:url" => @upload_url, 
+                                                          "wsdl:name" => file_name, 
+                                                          "wsdl:description" => description, 
+                                                          "wsdl:duration" => duration, 
+                                                          "wsdl:source" => "Ruby API Client",
+                                                          "wsdl:format" => file_format, 
+                                            "wsdl:isMultipleSpeakers" => multiple_speakers }
+                   
+        # Set the upload url to nil so that we don't reuse it             
+        @upload_url = nil
+
+        response
       end
 
-      def submit_recording(recording)
-        # initialize_session! unless @session.try :valid?
-        Submission.new(@session.session_id, recording, @savon).submit!
+      # Public: Calls the 'TranscribeRecording' SOAP Action
+      #
+      # recording_id - a String in GUID format
+      #
+      # Returns the SOAP response Hash
+      def transcribe_recording(recording_id)
+        # initialize_session unless @session.try :valid?
+
+        response = @savon.call :transcribe_recording, 
+                               message: { 'wsdl:sessionID'   => @session_id, 
+                                          'wsdl:recordingId' => recording_id }
+
+        response.body[:transcribe_recording_response][:transcribe_recording_result]
       end
 
-      def submit_recording_with_promocode(recording, promocode)
-        # initialize_session! unless @session.try :valid?
-        SubmissionWithPromocode.new(@session.session_id, recording, promocode, @savon).submit!
+      # Public: Calls the 'TranscribeRecordingWithPromoCode' SOAP Action
+      #
+      # recording_id - a String in GUID format
+      # promocode    - a String
+      #
+      # Returns the SOAP response Hash
+      def transcribe_recording_using_promocode(recording_id, promocode)
+        # initialize_session unless @session.try :valid?
+        
+        response = @savon.call :transcribe_recording_using_promocode, 
+                               message: { 'wsdl:sessionID'   => @session_id, 
+                                          'wsdl:recordingId' => recording_id,
+                                          'wsdl:promoCode'   => promocode }
+
+        response.body[:transcribe_recording_using_promocode_response][:transcribe_recording_using_promocode_result]
       end
 
-      def get_status(recording_id)
-        # raise "Login first!" unless @customer_login_id
-        CheckTranscriptionReady.new(@session.session_id, recording_id, @savon).check!
+      # Public: Calls the 'GetRecordingInfo' SOAP Action
+      #
+      # recording_id - a String in GUID format
+      #
+      # Returns the SOAP response Hash
+      def get_recording_info(recording_id)
+        response = @savon.call :get_recording_info,
+                    message: { 'wsdl:sessionID'   => @session_id,
+                               'wsdl:recordingID' => recording_id }
+        response.body[:get_recording_info_response][:get_recording_info_result]
       end
 
-      def logout!
-        # raise "Login first!" unless @customer_login_id
-        FinalizeSession.new(@session.session_id, @savon).submit!
+      # Public: Calls the 'GetTranscription' SOAP Action to allow for 
+      # downloading of transcriptions
+      #
+      # recording_id - a String in GUID format
+      # format       - a Symbol - either :text, :rtf, :pdf, :html
+      #
+      # Returns the file data in a String to write to a file (decoded from Base64.)
+      def get_transcription(recording_id, format = :text)
+        format_type = case format
+        when :text
+          "Text"
+        else
+          format.to_s.upcase
+        end
+
+        response = @savon.call :get_transcription, message: { 'wsdl:sessionID' => @session_id, 
+                                                              'wsdl:recId' => recording_id, 
+                                                              'wsdl:formattingType' => format_type }
+
+        error_message = response.body[:get_transcription_response][:error_message]
+        raise error_message if error_message
+
+        transcription = response.body[:get_transcription_response][:get_transcription_result]
+
+        raise "Transcription unable to be downloaded" if transcription.nil?
+
+        Base64.decode64(transcription)
+      end
+
+      # Public: Calls the 'FinalizeSession' SOAP Action to close 
+      # the session on the server
+      #
+      # Returns the SOAP response Hash
+      def finalize_session
+        @savon.call  :finalize_session, 
+                     message: { 'wsdl:sessionID' => @session_id }
       end
 
       private
 
+      # Private: Checks if the session expiry time has passed
+      #
+      # Returns a Boolean
       def session_valid?
-        if @session_expiry_time
-          @session_expiry_time > Time.now
-        end
+        @session_expiry_time > Time.now if @session_expiry_time
       end
 
-      
-
     end
 
   end
-end
+end