animoto 0.0.0.alpha0

data/lib/animoto/resource.rb

@@ -0,0 +1,153 @@
+module Animoto
+  class Resource
+    include ContentType
+    include StandardEnvelope
+    
+    # @overload endpoint(path)
+    #   Sets the endpoint for this class. This is the URL where all requests related
+    #   to this service will go.
+    #
+    #   @param [String] path the path to set
+    #   @return [String] the endpoint
+    #
+    # @overload endpoint()
+    #   Returns the endpoint for this class.
+    #
+    #   @return [String] the endpoint
+    def self.endpoint path = nil
+      @endpoint = path if path
+      @endpoint
+    end
+
+    # Returns the endpoint for this class.
+    # 
+    # @return [String] the endpoint
+    def endpoint
+      self.class.endpoint
+    end
+
+    # @overload payload_key(key)
+    #   Sets the payload key for this class. When building an instance of this class from
+    #   a response body, the payload key determines which object in the response payload
+    #   holds the attributes for the instance.
+    #
+    #   @param [String] key the key to set
+    #   @return [String] the key
+    #   
+    # @overload payload_key()
+    #   Returns the payload key for this class.
+    #
+    #   @return [String] the key
+    def self.payload_key key = nil
+      @payload_key = key if key
+      @payload_key || infer_content_type
+    end
+
+    # Returns the payload key for this class.
+    #
+    # @return [String] the key
+    def payload_key
+      self.class.payload_key
+    end
+    
+    # @private
+    #
+    # Makes a new instance of this class from a deserialized JSON response body. Note that
+    # it assumes the hash you're passing is structured correctly and does no format checking
+    # at all, so if the hash is not in the "standard envelope", this method will most likely
+    # raise an error.
+    #
+    # @param [Hash] body the deserialized JSON response body
+    # @return [Resource] an instance of this class
+    def self.load body
+      new unpack_standard_envelope(body)
+    end
+  
+    class << self
+      
+      # If an instance is instantiated with the same unique identifier (i.e. URL) as another,
+      # instead of creating a brand new object, will instead update and return the existing
+      # object. This way there should only be one object representing any one resource.
+      #
+      # @example
+      #   client = Animoto::Client.new
+      #   storyboard1 = Animoto::Storyboard.new :url => "https://api.animoto.com/storyboards/1"
+      #   storyboard2 = client.find! Animoto::Storyboard, "https://api.animoto.com/storyboards/1"
+      #   storyboard1.equal?(storyboard2) # => true
+      #
+      # @param [Hash] attributes a hash of attributes for this resource
+      # @return [Resource] either a new Resource instance, or an existing one with updated
+      #   attributes
+      alias_method :original_new, :new
+      def new attributes = {}
+        if attributes[:url] && instances[attributes[:url]]
+          instances[attributes[:url]].instantiate attributes
+        else
+          original_new attributes
+        end
+      end
+
+      # @private
+      # 
+      # Registers an instance in the identity map so that subsequent finds or instantiations
+      # of this resource with the same URL will return the same object.
+      #
+      # @param [Resource] instance the instance to register
+      # @raise [ArgumentError] if the instance isn't of this class
+      def register instance
+        raise ArgumentError unless instance.is_a?(self)
+        instances[instance.url] = instance
+      end
+      
+      private
+
+      # Returns (or vivifies) the identity map for this class.
+      #
+      # @return [Hash<String,Resource>] the identity map
+      def instances
+        @instances ||= {}
+      end
+    end
+    
+    attr_reader :url, :errors
+
+    def initialize attributes = {}
+      instantiate attributes
+    end
+    
+    # @private
+    #
+    # Update this instance with new attributes from the response body.
+    #
+    # @param [Hash] body deserialized JSON from a response body
+    # @return [self] this instance, updated
+    def load body = {}
+      instantiate unpack_standard_envelope(body)
+    end
+    
+    # @private
+    #
+    # Since Resources can be created a number of different ways, this method does
+    # the actual attribute setting for a Resource, acting much like a public version
+    # of #initialize.
+    #
+    # @param [Hash] attributes hash of attributes for this resource
+    # @return [self] this instance
+    def instantiate attributes = {}
+      @errors = (attributes[:errors] || []).collect { |e| wrap_error e  }      
+      @url    = attributes[:url]
+      self.class.register(self) if @url
+      self
+    end
+    
+    private 
+    
+    # Turns an error from a response body into a Ruby object.
+    #
+    # @param [Hash] error the error "object" from a response body
+    # @return [Error] a Ruby error object
+    def wrap_error error
+      Animoto::Error.new error['message']
+    end
+  end
+end

data/lib/animoto/song.rb

@@ -0,0 +1,16 @@
+module Animoto
+  class Song < Animoto::Asset
+    
+    attr_accessor :start_time, :duration, :title, :artist
+    
+    def to_hash
+      hash = super
+      hash['start_time'] = start_time if start_time
+      hash['duration'] = duration if duration
+      hash['title'] = title if title
+      hash['artist'] = artist if artist
+      hash
+    end
+    
+  end
+end

data/lib/animoto/standard_envelope.rb

@@ -0,0 +1,27 @@
+module Animoto
+  module StandardEnvelope
+    
+    def self.included base
+      base.class_eval {
+        include Animoto::StandardEnvelope::InstanceMethods
+        extend Animoto::StandardEnvelope::ClassMethods
+      }
+    end
+    
+    module InstanceMethods
+      def unpack_standard_envelope body = {}
+        self.class.unpack_standard_envelope body
+      end
+    end
+    
+    module ClassMethods
+      protected
+      def unpack_standard_envelope body = {}
+        {
+          :url => body['response']['payload'][payload_key]['links']['self'],
+          :errors => body['response']['status']['errors'] || []
+        }  
+      end
+    end
+  end
+end

data/lib/animoto/storyboard.rb

@@ -0,0 +1,22 @@
+module Animoto
+  class Storyboard < Animoto::Resource
+    
+    def self.unpack_standard_envelope body = {}
+      super.merge({
+        :duration => body['response']['payload'][payload_key]['metadata']['duration'],
+        :visuals_count => body['response']['payload'][payload_key]['metadata']['visuals_count'],
+        :preview_url => body['response']['payload'][payload_key]['links']['preview']
+      })
+    end
+    
+    attr_reader :duration, :visuals_count, :preview_url
+    
+    def instantiate attributes = {}
+      @duration = attributes[:duration]
+      @visuals_count = attributes[:visuals_count]
+      @preview_url = attributes[:preview_url]
+      super
+    end
+        
+  end
+end

data/lib/animoto/title_card.rb

@@ -0,0 +1,26 @@
+module Animoto
+  class TitleCard
+    include Animoto::Visual
+    
+    attr_accessor :title, :subtitle
+    
+    # Creates a new TitleCard.
+    #
+    # @param [String] title the main text
+    # @param [String] subtitle the secondary text
+    def initialize title, subtitle = nil
+      @title, @subtitle = title, subtitle
+    end
+    
+    # Returns a representation of this TitleCard as a Hash.
+    #
+    # @return [Hash] this TitleCard as a Hash
+    def to_hash
+      hash = super
+      hash['h1'] = title
+      hash['h2'] = subtitle if subtitle
+      hash['spotlit'] = spotlit? unless @spotlit.nil?
+      hash
+    end
+  end
+end

data/lib/animoto/video.rb

@@ -0,0 +1,29 @@
+module Animoto
+  class Video < Animoto::Resource
+    
+    def self.unpack_standard_envelope body
+      super.merge({
+        :download_url => body['response']['payload'][payload_key]['links']['download'],
+        :storyboard_url => body['response']['payload'][payload_key]['links']['storyboard'],
+        :duration => body['response']['payload'][payload_key]['metadata']['duration'],
+        :format   => body['response']['payload'][payload_key]['metadata']['format'],
+        :framerate  => body['response']['payload'][payload_key]['metadata']['framerate'],
+        :resolution => body['response']['payload'][payload_key]['metadata']['vertical_resolution']
+      })
+    end
+
+    attr_reader :download_url, :storyboard_url, :storyboard, :duration, :format, :framerate, :resolution
+
+    def instantiate attributes = {}
+      @download_url = attributes[:download_url]
+      @storyboard_url = attributes[:storyboard_url]
+      @storyboard = Animoto::Storyboard.new(:url => @storyboard_url) if @storyboard_url
+      @duration = attributes[:duration]
+      @format = attributes[:format]
+      @framerate = attributes[:framerate]
+      @resolution = attributes[:resolution]
+      super
+    end
+
+  end
+end

data/lib/animoto/visual.rb

@@ -0,0 +1,30 @@
+module Animoto
+  module Visual
+    
+    # Setter for spotlighting, which instructs the director to give special attention
+    # to this visual when directing.
+    #
+    # @param [Boolean] bool true if this visual should receive special attention
+    def spotlit= bool
+      @spotlit = bool
+    end
+    
+    # Returns true if this visual is spotlit.
+    #
+    # @return [Boolean] whether or not this visual is spotlit
+    def spotlit?
+      @spotlit
+    end
+
+    # Returns a representation of this Visual as a Hash
+    #
+    # @return [Hash] this Visual as a Hash
+    def to_hash
+      hash = super rescue {}
+      hash['spotlit'] = spotlit? unless @spotlit.nil?
+      hash['type'] = self.class.name.split('::').last.gsub(/(^)?([A-Z])/) { "#{'_' unless $1}#{$2.downcase}" }
+      hash
+    end
+    
+  end
+end

data/lib/animoto.rb

@@ -0,0 +1,5 @@
+module Animoto
+  def self.version
+    "0.0.0.alpha0"
+  end
+end

data/spec/animoto/asset_spec.rb

@@ -0,0 +1 @@
+require File.expand_path(File.dirname(__FILE__) + "/../spec_helper")

data/spec/animoto/client_spec.rb

@@ -0,0 +1,119 @@
+require File.expand_path(File.dirname(__FILE__) + "/../spec_helper")
+
+describe Animoto::Client do
+  def client options = {}
+    @client ||= Animoto::Client.new "joe", "secret", options
+  end
+
+  def object
+    @object ||= Object.new
+  end
+
+  describe "supplying credentials" do
+    describe "manually" do
+      it "should accept the key and secret as the first two parameters on initialization" do
+        c = Animoto::Client.new "key", "secret"
+        c.key.should == "key"
+        c.secret.should == "secret"
+      end
+      
+      describe "when the secret isn't specified (i.e. only 1 parameter was passed)" do
+        before do
+          File.stubs(:exist?).returns(false) # <= to keep it from finding our .animotorc files
+        end
+        
+        it "should raise an error" do
+          lambda { Animoto::Client.new "key" }.should raise_error
+        end
+      end
+    end
+    
+    describe "automatically" do
+      before do
+        @home_path  = File.expand_path("~/.animotorc")
+        @etc_path   = "/etc/.animotorc"
+        @config     = "key: joe\nsecret: secret"
+      end
+      
+      describe "when ~/.animotorc exists" do
+        before do
+          File.stubs(:exist?).with(@home_path).returns(true)
+          File.stubs(:read).with(@home_path).returns(@config)
+        end
+        
+        it "should configure itself based on the options in ~/.animotorc" do
+          c = Animoto::Client.new
+          c.key.should == "joe"
+          c.secret.should == "secret"
+        end
+      end
+      
+      describe "when ~/.animotorc doesn't exist" do
+        before do
+          File.stubs(:exist?).with(@home_path).returns(false)
+        end
+        
+        describe "when /etc/.animotorc exists" do
+          before do
+            File.stubs(:exist?).with(@etc_path).returns(true)
+            File.stubs(:read).with(@etc_path).returns(@config)
+          end
+          
+          it "should configure itself based on the options in /etc/.animotorc" do
+            c = Animoto::Client.new
+            c.key.should == "joe"
+            c.secret.should == "secret"
+          end
+        end
+        
+        describe "when /etc/.animotorc doesn't exist" do
+          it "should raise an error" do
+            lambda { Animoto::Client.new }.should raise_error
+          end
+        end
+      end
+    end
+  end
+  
+  describe "finding an instance by identifier" do
+    before do
+      @url = "https://api.animoto.com/storyboards/1"
+      @body = {'response'=>{'status'=>{'code'=>200}},'payload'=>{'storyboard'=>{'links'=>{'self'=>@url}}}}
+      stub_request(:get, @url).to_return(:body => @body.to_json, :status => [200,"OK"])
+    end
+    
+    it "should make a GET request to the given url" do
+      client.find(Animoto::Storyboard, @url)
+      WebMock.should have_requested(:get, @url)
+    end
+    
+    it "should ask for a response in the proper format" do
+      client.find(Animoto::Storyboard, @url)
+      WebMock.should have_requested(:get, @url).with(:headers => { 'Accept' => "application/vnd.animoto.storyboard-v1+json"})
+    end
+    
+    it "should not sent a request body" do
+      client.find(Animoto::Storyboard, @url)
+      WebMock.should have_requested(:get, @url).with(:body => "")
+    end
+    
+    it "should return an instance of the correct resource type" do
+      client.find(Animoto::Storyboard, @url).should be_an_instance_of(Animoto::Storyboard)
+    end    
+  end
+  
+  describe "reloading an instance" do
+    before do
+      @url = 'https://api.animoto.com/jobs/directing/1'
+      @job = Animoto::DirectingJob.new :state => 'initial', :url => @url
+      @body = {'response'=>{'status'=>{'code'=>200}},'payload'=>{'directing_job'=>{'state'=>'retrieving_assets','links'=>{'self'=>@url}}}}
+      stub_request(:get, @url).to_return(:body => @body.to_json, :status => [200,"OK"])
+      @job.state.should == 'initial' # sanity check
+    end
+    
+    it "should update the resource's attributes" do
+      client.reload!(@job)
+      @job.state.should == 'retrieving_assets'
+    end
+  end
+end

data/spec/animoto/directing_and_rendering_job_spec.rb

@@ -0,0 +1,45 @@
+require File.expand_path(File.dirname(__FILE__) + "/../spec_helper")
+
+describe Animoto::DirectingAndRenderingJob do
+  
+  it "should have endpoint '/jobs/directing_and_rendering'" do
+    Animoto::DirectingAndRenderingJob.endpoint.should == '/jobs/directing_and_rendering'
+  end
+  
+  it "should have content_type 'application/vnd.animoto.directing_and_rendering_job'" do
+    Animoto::DirectingAndRenderingJob.content_type.should == 'directing_and_rendering_job'
+  end
+  
+  it "should have payload key 'directing_and_rendering_job'" do
+    Animoto::DirectingAndRenderingJob.payload_key.should == 'directing_and_rendering_job'
+  end
+  
+  describe "loading from a response body" do
+    before do
+      @body = {
+        'response' => {
+          'status' => { 'code' => 200 },
+          'payload' => {
+            'directing_and_rendering_job' => {
+              'state' => 'completed',
+              'links' => {
+                'self' => 'http://animoto.com/jobs/directing_and_rendering/1',
+                'video' => 'http://animoto.com/videos/1'
+              }
+            }
+          }
+        }
+      }
+      @job = Animoto::DirectingAndRenderingJob.load @body
+    end
+    
+    it "should set the video url from the body" do
+      @job.video_url.should == 'http://animoto.com/videos/1'
+    end
+    
+    it "should create a video from the video url" do
+      @job.video.should be_an_instance_of(Animoto::Video)
+      @job.video.url.should == @job.video_url
+    end
+  end  
+end

data/spec/animoto/directing_and_rendering_manifest_spec.rb

@@ -0,0 +1,143 @@
+require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+
+describe Animoto::DirectingAndRenderingManifest do
+  
+  def manifest options = {}
+    @manifest ||= Animoto::DirectingAndRenderingManifest.new options
+  end
+  
+  describe "generating a hash" do
+    before do
+      manifest(:title => 'Funderful Wonderment', :producer => 'Senor Spielbergo', :pacing => 'double',
+        :resolution => "720p", :framerate => 24, :format => 'flv')
+      @image = manifest.add_image 'http://website.com/image.png'
+      @title_card = manifest.add_title_card 'woohoo', 'this is awesome'
+      @footage = manifest.add_footage 'http://website.com/movie.mp4'
+      @song_obj = manifest.add_song 'http://website.com/song.mp3'
+    end
+    
+    it "should have top-level 'directing_and_rendering_job' object" do
+      manifest.to_hash.should have_key('directing_and_rendering_job')
+      manifest.to_hash['directing_and_rendering_job'].should be_a(Hash)
+    end
+
+    describe "when the callback url is set" do
+      before do
+        manifest.http_callback_url = 'http://website.com/callback'        
+      end
+
+      describe "but the callback format isn't" do
+        it "should raise an error" do
+          lambda { manifest.to_hash }.should raise_error(ArgumentError)
+        end
+      end
+  
+      describe "as well as the format" do
+        before do
+          manifest.http_callback_format = 'xml'
+        end
+    
+        it "should have the HTTP callback URL in the job" do
+          manifest.to_hash['directing_and_rendering_job'].should have_key('http_callback')
+          manifest.to_hash['directing_and_rendering_job']['http_callback'].should == manifest.http_callback_url
+        end
+
+        it "should have the HTTP callback format in the job" do
+          manifest.to_hash['directing_and_rendering_job'].should have_key('http_callback_format')
+          manifest.to_hash['directing_and_rendering_job']['http_callback_format'].should == manifest.http_callback_format
+        end
+      end
+    end
+    
+    it "should have a 'directing_manifest' object within the job" do
+      manifest.to_hash['directing_and_rendering_job'].should have_key('directing_manifest')
+      manifest.to_hash['directing_and_rendering_job']['directing_manifest'].should be_a(Hash)
+    end
+    
+    describe "directing_manifest" do
+      before do
+        @hash = manifest.to_hash['directing_and_rendering_job']['directing_manifest']
+      end
+      
+      it "should have a 'style' key in the manifest" do
+        @hash.should have_key('style')
+        @hash['style'].should == manifest.style
+      end
+    
+      it "should have a 'pacing' key in the manifest" do
+        @hash.should have_key('pacing')
+        @hash['pacing'].should == manifest.pacing
+      end
+    
+      it "should have a 'producer_name' key in the manifest" do
+        @hash.should have_key('producer_name')
+        @hash['producer_name'].should == manifest.producer
+      end
+    
+      it "should have a 'visuals' key in the manifest" do
+        @hash.should have_key('visuals')
+      end
+    
+      it "should have a 'song' object in the manifest" do
+        @hash.should have_key('song')
+        @hash['song'].should be_a(Hash)
+      end
+    
+      describe "visuals array" do
+        before do
+          @visuals = @hash['visuals']
+        end
+      
+        it "should have the visuals in the order they were added" do
+          @visuals[0].should == @image.to_hash
+          @visuals[1].should == @title_card.to_hash
+          @visuals[2].should == @footage.to_hash
+        end
+      end
+    
+      describe "song" do
+        before do
+          @song = @hash['song']
+        end
+      
+        it "should have info about the song" do
+          @song.should == @song_obj.to_hash
+        end
+      end
+    end
+
+    it "should have a 'rendering_manifest' object within the job" do
+      manifest.to_hash['directing_and_rendering_job'].should have_key('rendering_manifest')
+      manifest.to_hash['directing_and_rendering_job']['rendering_manifest'].should be_a(Hash)
+    end
+
+    describe "rendering_manifest" do
+      before do
+        @hash = manifest.to_hash['directing_and_rendering_job']['rendering_manifest']
+      end
+      
+      it "should have a 'rendering_profile' object in the manifest" do
+        @hash.should have_key('rendering_profile')
+        @hash['rendering_profile'].should be_a(Hash)
+      end
+
+      describe "rendering_profile" do
+        before do
+          @profile = @hash['rendering_profile']
+        end
+
+        it "should have a 'vertical_resolution' key" do
+          @profile['vertical_resolution'].should == manifest.resolution
+        end
+
+        it "should have a 'framerate' key" do
+          @profile['framerate'].should == manifest.framerate
+        end
+
+        it "should have a 'format' key" do
+          @profile['format'].should == manifest.format
+        end
+      end
+    end
+  end  
+end

data/spec/animoto/directing_job_spec.rb

@@ -0,0 +1,48 @@
+require File.expand_path(File.dirname(__FILE__) + "/../spec_helper")
+
+describe Animoto::DirectingJob do
+  
+  it "should have endpoint '/jobs/directing'" do
+    Animoto::DirectingJob.endpoint.should == '/jobs/directing'
+  end
+  
+  it "should have content type 'application/vnd.animoto.directing_job'" do
+    Animoto::DirectingJob.content_type.should == 'directing_job'
+  end
+  
+  it "should have payload key 'directing_job'" do
+    Animoto::DirectingJob.payload_key.should == 'directing_job'
+  end
+  
+  describe "loading from a response body" do
+    before do
+      @body = {
+        'response' => {
+          'status' => {
+            'code' => 200
+          },
+          'payload' => {
+            'directing_job' => {
+              'state' => 'completed',
+              'links' => {
+                'self' => 'http://animoto.com/jobs/directing/1',
+                'storyboard' => 'http://animoto.com/storyboards/1'
+              }
+            }
+          }
+        }
+      }
+      @job = Animoto::DirectingJob.load @body
+    end
+    
+    it "should set the storyboard url from the body" do
+      @job.storyboard_url.should == 'http://animoto.com/storyboards/1'
+    end
+    
+    it "should create a storyboard from the storyboard url" do
+      @job.storyboard.should be_an_instance_of(Animoto::Storyboard)
+      @job.storyboard.url.should == @job.storyboard_url
+    end
+  end
+  
+end