animoto 0.1.1.beta1 → 1.0.0

data/README.md

@@ -35,14 +35,14 @@ This document does not cover the details of the Animoto API itself. For such inf
 
 You can install the Animoto API Ruby Client either through [RubyGems](http://rubygems.org):
 
-    gem install animoto -v 0.1.0.alpha0 --pre
+    gem install animoto
 
 Or by cloning [the repository](http://github.com/animoto/animoto_api_client_ruby) on [GitHub](http://github.com/) and building it from source:
 
     git clone git://github.com/animoto/animoto_api_client_ruby.git
     cd animoto_api_client_ruby
     gem build animoto.gemspec
-    gem install animoto-0.1.0.alpha0.gem
+    gem install animoto-1.0.0.gem
 
 ### Prerequisites
 
@@ -102,7 +102,6 @@ client and using HTTP callbacks for status updates.
     # and format.
     manifest = Manifests::DirectingAndRendering.new(
       :title => "Amazing Title!", 
-      :producer => "Fishy Joe", 
       :resolution => "720p", 
       :framerate => 24, 
       :format => 'h264'
@@ -167,7 +166,12 @@ status.
     
       # Now it's time to render the storyboard into a video.  First we create
       # a rendering manifest.
-    	manifest = Manifests::Rendering.new(storyboard, :resolution => "720p", :framerate => 24, :format => 'h264')
+    	manifest = Manifests::Rendering.new(
+    	  storyboard,
+    	  :resolution => "720p",
+    	  :framerate => 24,
+    	  :format => 'h264'
+    	)
     	
     	# Send the manifest to the API.
     	rendering_job = client.render!(manifest)

data/lib/animoto.rb

@@ -6,6 +6,6 @@ module Animoto
   #
   # @return [String]
   def self.version
-    "0.1.1.beta1"
+    "1.0.0"
   end
 end

data/lib/animoto/assets/base.rb

@@ -19,7 +19,7 @@ module Animoto
       # Returns a representation of this asset as a Hash. Used mainly for generating
       # manifests.
       #
-      # @return [Hash<String,Object>] this asset as a Hash
+      # @return [Hash{String=>Object}] this asset as a Hash
       def to_hash
         { 'source_url' => @source }
       end

data/lib/animoto/assets/footage.rb

@@ -19,7 +19,7 @@ module Animoto
     
       # Returns a representation of this Footage as a Hash.
       #
-      # @return [Hash<String,Object>] this asset as a Hash
+      # @return [Hash{String=>Object}] this asset as a Hash
       # @see Animoto::Support::Visual#to_hash
       # @see Animoto::Assets::Base#to_hash
       def to_hash

data/lib/animoto/assets/image.rb

@@ -10,7 +10,7 @@ module Animoto
     
       # Returns a representation of this Image as a Hash.
       #
-      # @return [Hash<String,Object>] this asset as a Hash
+      # @return [Hash{String=>Object}] this asset as a Hash
       # @see Animoto::Support::Visual#to_hash
       # @see Animoto::Assets::Base#to_hash
       def to_hash

data/lib/animoto/assets/song.rb

@@ -13,7 +13,7 @@ module Animoto
     
       # Returns a representation of this Song as a Hash.
       #
-      # @return [Hash<String,Object>] this asset as a Hash
+      # @return [Hash{String=>Object}] this asset as a Hash
       # @see Animoto::Assets::Base#to_hash
       def to_hash
         hash = super

data/lib/animoto/assets/title_card.rb

@@ -21,7 +21,7 @@ module Animoto
     
       # Returns a representation of this TitleCard as a Hash.
       #
-      # @return [Hash<String,Object>] this TitleCard as a Hash
+      # @return [Hash{String=>Object}] this TitleCard as a Hash
       # @see Animoto::Support::Visual#to_hash
       def to_hash
         hash = super

data/lib/animoto/client.rb

@@ -6,7 +6,9 @@ require 'animoto/support/content_type'
 require 'animoto/support/coverable'
 require 'animoto/support/dynamic_class_loader'
 require 'animoto/support/errors'
+require 'animoto/support/hash'
 require 'animoto/support/standard_envelope'
+require 'animoto/support/string'
 require 'animoto/support/visual'
 
 require 'animoto/resources/base'
@@ -28,18 +30,19 @@ require 'animoto/manifests/directing'
 require 'animoto/manifests/directing_and_rendering'
 require 'animoto/manifests/rendering'
 
-require 'animoto/callbacks/base'
-require 'animoto/callbacks/directing'
-require 'animoto/callbacks/directing_and_rendering'
-require 'animoto/callbacks/rendering'
-
 require 'animoto/http_engines/base'
 require 'animoto/response_parsers/base'
 
 module Animoto
   class Client
+    
+    # The default endpoint where requests go.
     API_ENDPOINT      = "https://api2-sandbox.animoto.com/"
+    
+    # The version of the Animoto API this client targets.
     API_VERSION       = 1
+    
+    # The common prefix all vendor-specific Animoto content types share.
     BASE_CONTENT_TYPE = "application/vnd.animoto"
     
     # Your API key.
@@ -149,25 +152,16 @@ module Animoto
     #
     # @param [Class] klass the resource class you're finding
     # @param [String] url the URL of the resource you want
-    # @param [Hash<Symbol,Object>] options
+    # @param [Hash{Symbol=>Object}] options
     # @return [Resources::Base] the resource object found
     def find klass, url, options = {}
       klass.load(find_request(klass, url, options))
     end
-    
-    # Returns a callback object of the specified type given the callback body.
-    #
-    # @param [Class] klass the callback class
-    # @param [String] body the HTTP body of the callback
-    # @return [Callbacks::Base] the callback object
-    def process_callback klass, body
-      klass.new(response_parser.parse(body))
-    end
-    
+        
     # Sends a request to start directing a storyboard.
     #
     # @param [Manifests::Directing] manifest the manifest to direct
-    # @param [Hash<Symbol,Object>] options
+    # @param [Hash{Symbol=>Object}] options
     # @return [Jobs::Directing] a job to monitor the status of the directing
     def direct! manifest, options = {}
       Resources::Jobs::Directing.load(send_manifest(manifest, Resources::Jobs::Directing.endpoint, options))
@@ -176,7 +170,7 @@ module Animoto
     # Sends a request to start rendering a video.
     #
     # @param [Manifests::Rendering] manifest the manifest to render
-    # @param [Hash<Symbol,Object>] options
+    # @param [Hash{Symbol=>Object}] options
     # @return [Jobs::Rendering] a job to monitor the status of the rendering
     def render! manifest, options = {}
       Resources::Jobs::Rendering.load(send_manifest(manifest, Resources::Jobs::Rendering.endpoint, options))
@@ -185,7 +179,7 @@ module Animoto
     # Sends a request to start directing and rendering a video.
     #
     # @param [Manifests::DirectingAndRendering] manifest the manifest to direct and render
-    # @param [Hash<Symbol,Object>] options
+    # @param [Hash{Symbol=>Object}] options
     # @return [Jobs::DirectingAndRendering] a job to monitor the status of the directing and rendering
     def direct_and_render! manifest, options = {}
       Resources::Jobs::DirectingAndRendering.load(send_manifest(manifest, Resources::Jobs::DirectingAndRendering.endpoint, options))
@@ -195,7 +189,7 @@ module Animoto
     # see if it's ready if you are not using HTTP callbacks.
     #
     # @param [Resources::Base] resource the resource to update
-    # @param [Hash<Symbol,Object>] options
+    # @param [Hash{Symbol=>Object}] options
     # @return [Resources::Base] the given resource with the latest attributes
     def reload! resource, options = {}
       resource.load(find_request(resource.class, resource.url, options))
@@ -231,8 +225,8 @@ module Animoto
     #
     # @param [Class] klass the Resource class you're looking for
     # @param [String] url the URL of the resource
-    # @param [Hash<Symbol,Object>] options
-    # @return [Hash<String,Object>] deserialized response body
+    # @param [Hash{Symbol=>Object}] options
+    # @return [Hash{String=>Object}] deserialized response body
     def find_request klass, url, options = {}
       request(:get, url, nil, { "Accept" => content_type_of(klass) }, options)
     end
@@ -241,8 +235,8 @@ module Animoto
     #
     # @param [Manifests::Base] manifest the manifest being acted on
     # @param [String] endpoint the endpoint to send the request to
-    # @param [Hash<Symbol,Object>] options
-    # @return [Hash<String,Object>] deserialized response body
+    # @param [Hash{Symbol=>Object}] options
+    # @return [Hash{String=>Object}] deserialized response body
     def send_manifest manifest, endpoint, options = {}
       u = URI.parse(self.endpoint)
       u.path = endpoint
@@ -260,10 +254,10 @@ module Animoto
     # @param [Symbol] method which HTTP method to use (should be lowercase, i.e. :get instead of :GET)
     # @param [String] url the URL of the request
     # @param [String,nil] body the request body
-    # @param [Hash<String,String>] headers the request headers (will be sent as-is, which means you should
+    # @param [Hash{String=>String}] headers the request headers (will be sent as-is, which means you should
     #   specify "Content-Type" => "..." instead of, say, :content_type => "...")
-    # @param [Hash<Symbol,Object>] options
-    # @return [Hash<String,Object>] deserialized response body
+    # @param [Hash{Symbol=>Object}] options
+    # @return [Hash{String=>Object}] deserialized response body
     # @raise [Error]
     def request method, url, body, headers = {}, options = {}
       code, body = catch(:fail) do

data/lib/animoto/http_engines/base.rb

@@ -1,7 +1,15 @@
 module Animoto
-  module HTTPEngines
-    extend Support::DynamicClassLoader(File.expand_path(File.dirname(__FILE__)))
+  module HTTPEngines    
+    extend Support::DynamicClassLoader
     
+    dynamic_class_path File.expand_path(File.dirname(__FILE__))
+    
+    adapter 'Curl'
+    adapter 'NetHTTP'
+    adapter 'Patron'
+    adapter 'RestClient'
+    adapter 'Typhoeus'
+        
     # @abstract Override {#request} to subclass.
     class Base
       
@@ -12,23 +20,23 @@ module Animoto
       #   instead of :GET)
       # @param [String] url the URL to request
       # @param [String,nil] body the request body
-      # @param [Hash<String,String>] headers request headers to send; names will be sent as-is
+      # @param [Hash{String=>String}] headers request headers to send; names will be sent as-is
       #   (for example, use keys like "Content-Type" and not :content_type)
-      # @param [Hash<Symbol,Object>] options
+      # @param [Hash{Symbol=>Object}] options
       # @option options [Integer] :timeout set a timeout
       # @option options [String] :username the authentication username
       # @option options [String] :password the authentication password
       # @return [String] the response body
-      # @raise [NotImplementedError] if called on the abstract class
+      # @raise [AbstractMethodError] if called on the abstract class
       def request method, url, body = nil, headers = {}, options = {}
-        raise NotImplementedError
+        raise AbstractMethodError
       end
     
       private
     
       # Checks the response and raises an error if the status isn't success.
       #
-      # @param [Fixnum] code the HTTP status code
+      # @param [Integer] code the HTTP status code
       # @param [String] body the HTTP response body
       # @return [void]
       # @raise [Animoto::Error] if the status isn't between 200 and 299

data/lib/animoto/http_engines/curl_adapter.rb

@@ -19,7 +19,7 @@ module Animoto
       # @param [Symbol] method the HTTP method
       # @param [String] url the URL to request
       # @param [String,nil] body the request body
-      # @param [Hash<String,String>] headers hash of HTTP request headers
+      # @param [Hash{String=>String}] headers hash of HTTP request headers
       # @return [Curl::Easy] the Easy instance
       def build_curl method, url, body, headers, options
         ::Curl::Easy.new(url) do |c|
@@ -36,6 +36,7 @@ module Animoto
       # @param [Curl::Easy] curl the Easy object with the request parameters
       # @param [Symbol] method the HTTP method to use
       # @param [String] body the HTTP request body
+      # @return [void]
       def perform curl, method, body
         case method
         when :get
@@ -44,8 +45,6 @@ module Animoto
           curl.http_post(body)
         end
       end
-    end
-    
-    adapter_map.merge! :curl => CurlAdapter
+    end    
   end
 end

data/lib/animoto/http_engines/net_http_adapter.rb

@@ -39,9 +39,9 @@ module Animoto
       # @param [Symbol] method which HTTP method to use (should be lowercase, i.e. :get instead of :GET)
       # @param [String] uri the request path
       # @param [String,nil] body the request body
-      # @param [Hash<String,String>] headers the request headers (will be sent as-is, which means you should
+      # @param [Hash{String=>String}] headers the request headers (will be sent as-is, which means you should
       #   specify "Content-Type" => "..." instead of, say, :content_type => "...")
-      # @param [Hash<Symbol,Object>] options
+      # @param [Hash{Symbol=>Object}] options
       # @return [Net::HTTPRequest] the request object
       def build_request method, uri, body, headers, options
         req = HTTP_METHOD_MAP[method].new uri.path
@@ -50,8 +50,6 @@ module Animoto
         req.basic_auth options[:username], options[:password]
         req
       end      
-    end
-    
-    adapter_map.merge! :net_http => NetHTTPAdapter
+    end    
   end
 end

data/lib/animoto/http_engines/patron_adapter.rb

@@ -16,7 +16,7 @@ module Animoto
       
       # Builds the Session object.
       #
-      # @param [Hash<Symbol,Object>] options options for the Session
+      # @param [Hash{Symbol=>Object}] options options for the Session
       # @return [Patron::Session] the Session object
       def build_session options
         session = ::Patron::Session.new
@@ -25,8 +25,6 @@ module Animoto
         session.password = options[:password]
         session
       end
-    end
-    
-    adapter_map.merge! :patron => PatronAdapter
+    end    
   end
 end

data/lib/animoto/http_engines/rest_client_adapter.rb

@@ -18,8 +18,6 @@ module Animoto
         check_response response.code, response.body
         response.body
       end
-    end
-    
-    adapter_map.merge! :rest_client => RestClientAdapter
+    end    
   end
 end

data/lib/animoto/http_engines/typhoeus_adapter.rb

@@ -17,8 +17,6 @@ module Animoto
         check_response response.code, response.body
         response.body
       end   
-    end
-    
-    adapter_map.merge! :typhoeus => TyphoeusAdapter
+    end    
   end
 end

data/lib/animoto/manifests/base.rb

@@ -13,7 +13,7 @@ module Animoto
       # Returns a representation of this manifest as a Hash, used to populate
       # request bodies when directing, rendering, etc.
       #
-      # @return [Hash<String,Object>] the manifest as a Hash
+      # @return [Hash{String=>Object}] the manifest as a Hash
       def to_hash
         {}
       end

data/lib/animoto/manifests/directing.rb

@@ -119,7 +119,7 @@ module Animoto
 
       # Returns a representation of this manifest as a Hash.
       #
-      # @return [Hash<String,String>] the manifest as a Hash
+      # @return [Hash{String=>Object}] the manifest as a Hash
       # @raise [ArgumentError] if a callback URL is specified but not the format
       def to_hash options = {}
         hash = { 'directing_job' => { 'directing_manifest' => {} } }

data/lib/animoto/manifests/directing_and_rendering.rb

@@ -1,48 +1,75 @@
 module Animoto
   module Manifests
-    class DirectingAndRendering < Animoto::Manifests::Directing
-      
-      # The vertical resolution of the rendered video. Valid values are '180p', '270p',
-      # '360p', '480p', '576p', '720p' or '1080p'.
-      # @return [String]
-      attr_accessor :resolution
+    
+    # A directing-and-rendering manifest is little more than just a single envelope
+    # with a directing manifest and a rendering manifest embedded within.
+    class DirectingAndRendering < Animoto::Manifests::Base
       
-      # The framerate of the rendered video. Valid values are 12, 15, 24 or 30.
-      # @return [Fixnum]
-      attr_accessor :framerate
+      # The embedded directing manifest
+      # @return [Manifests::Directing]
+      attr_reader :directing_manifest
       
-      # The format of the rendered video. Valid values are 'h264', 'h264-iphone', 'flv' or 'iso'.
+      # The embedded rendering manifest
+      # @return [Manifests::Rendering]
+      attr_reader :rendering_manifest
+
+      # A URL to receive a callback after directing is finished.
       # @return [String]
-      attr_accessor :format
+      attr_accessor :http_callback_url
       
+      # The format of the callback; either 'xml' or 'json'.
+      # @return [String]
+      attr_accessor :http_callback_format
+
       # Creates a new directing-and-rendering manifest.
       #
-      # @param [Hash<Symbol,Object>] options
+      # @param [Hash{Symbol=>Object}] options
+      # @option options [String] :title the title of this project
+      # @option options [String] :pacing ('default') the pacing for this project
       # @option options [String] :resolution the vertical resolution of the rendered video
       # @option options [Integer] :framerate the framerate of the rendered video
       # @option options [String] :format the format of the rendered video
-      # @return [Manifests::DirectingAndRendering] the manifest
-      # @see Animoto::Manifests::Directing#initialize
-      def initialize options = {}
-        super
-        @resolution = options[:resolution]
-        @framerate  = options[:framerate]
-        @format     = options[:format]
+      # @option options [String] :http_callback_url a URL to receive a callback when this job is done
+      # @option options [String] :http_callback_format the format of the callback
+      def initialize options = {}        
+        @directing_manifest = Manifests::Directing.new(options.only(:title, :pacing))
+        @rendering_manifest = Manifests::Rendering.new(options.only(:resolution, :framerate, :format))
+        
+        @http_callback_url  = options[:http_callback_url]
+        @http_callback_format = options[:http_callback_format]
       end
-    
+
+      # Delegates method calls to the underlying directing or rendering manifests if
+      # they respond to the call.
+      #
+      # @raise [NoMethodError] if the underlying manifests don't respond
+      def method_missing *args
+        name = args.first
+        if directing_manifest.respond_to?(name)
+          directing_manifest.__send__ *args
+        elsif rendering_manifest.respond_to?(name)
+          rendering_manifest.__send__ *args
+        else
+          super
+        end
+      end
+
       # Returns a representation of this manifest as a Hash.
       #
-      # @return [Hash<String,String>] the manifest as a Hash
+      # @return [Hash{String=>Object}] the manifest as a Hash
       # @raise [ArgumentError] if a callback URL is specified but not the format
       # @see Animoto::Manifests::Directing#to_hash
+      # @see Animoto::Manifests::Rendering#to_hash
       def to_hash options = {}
-        hash  = super
-        directing_job = hash.delete('directing_job')
-        hash['directing_and_rendering_job'] = directing_job.merge('rendering_manifest' => { 'rendering_parameters' => {}})
-        params = hash['directing_and_rendering_job']['rendering_manifest']['rendering_parameters']
-        params['resolution'] = resolution
-        params['framerate'] = framerate
-        params['format'] = format
+        hash  = { 'directing_and_rendering_job' => {} }
+        job   = hash['directing_and_rendering_job']
+        if http_callback_url
+          raise ArgumentError, "You must specify a http_callback_format (either 'xml' or 'json')" if http_callback_format.nil?
+          job['http_callback'] = http_callback_url
+          job['http_callback_format'] = http_callback_format
+        end
+        job['directing_manifest'] = self.directing_manifest.to_hash['directing_job']['directing_manifest']
+        job['rendering_manifest'] = self.rendering_manifest.to_hash['rendering_job']['rendering_manifest']
         hash
       end