episodic-platform 0.9

data/History.txt

@@ -0,0 +1,4 @@
+=== 0.0.9 2010-02-10
+
+* 1 major enhancement:
+  * Initial release

data/Manifest.txt

@@ -0,0 +1,35 @@
+History.txt
+Manifest.txt
+PostInstall.txt
+README.rdoc
+Rakefile
+lib/episodic/platform.rb
+lib/episodic/platform/analytics_methods.rb
+lib/episodic/platform/base.rb
+lib/episodic/platform/collection_response.rb
+lib/episodic/platform/connection.rb
+lib/episodic/platform/exceptions.rb
+lib/episodic/platform/query_methods.rb
+lib/episodic/platform/response.rb
+lib/episodic/platform/write_methods.rb
+script/console
+script/destroy
+script/generate
+test/fixtures/1-0.mp4
+test/fixtures/create-episode-response-s3.xml
+test/fixtures/create-episode-response.xml
+test/fixtures/episodes-response.xml
+test/fixtures/episodes-summary-report-response.xml
+test/fixtures/invalid-param-response-multiple.xml
+test/fixtures/invalid-param-response-single.xml
+test/fixtures/playlists-response.xml
+test/fixtures/shows-response.xml
+test/test_analytics_requests.rb
+test/test_analytics_responses.rb
+test/test_connection.rb
+test/test_error_responses.rb
+test/test_helper.rb
+test/test_query_requests.rb
+test/test_query_responses.rb
+test/test_write_requests.rb
+test/test_write_responses.rb

data/PostInstall.txt

@@ -0,0 +1,7 @@
+
+For more information on episodic-platform, see http://episodic.github.com/episodic-platform-ruby
+
+NOTE: Change this information in PostInstall.txt 
+You can also delete it if you don't want it.
+
+

data/README.rdoc

@@ -0,0 +1,86 @@
+= Episodic Platform SDK for Ruby
+
+* http://github.com/episodic/episodic-platform-ruby
+
+== DESCRIPTION:
+
+Ruby client library for Episodic's Platform REST API
+
+For more information about Episodic's Platform API see {http://app.episodic.com/help/server_api}[http://app.episodic.com/help/server_api]
+
+Rdocs are located at {http://episodic.github.com/episodic-platform-ruby/doc/index.html}[http://episodic.github.com/episodic-platform-ruby/doc/index.html]
+
+== GETTING STARTED:
+  
+To get started you need to require 'episodic/platform':
+
+  require 'episodic/platform'
+	 
+Before you can use any of the object methods, you need to create a connection using <tt>Base.establish_connection!</tt>. The 
+<tt>Base.establish_connection!</tt> method requires that you pass your Episodic API Key and Episodic Secret Key.
+  
+  Episodic::Platform::Base.establish_connection!('my_api_key', 'my_secret_key')
+
+After establishing a connection you can call any of the methods in the <tt>Episodic::Platform::QueryMehtods</tt>, <tt>Episodic::Platform::WriteMehtods</tt>
+or <tt>Episodic::Platform::AnaylticsMehtods</tt>. Generally these methods will return some subclass of <tt>Episodic::Platform::Response</tt> which
+contains the parsed response. However, you can also access the XML response body directly by calling <tt>response.xml</tt>.
+
+== SAMPLE USAGE:
+
+To query for a list of episodes:
+
+  response = Episodic::Platform::QueryMethods.episodes({:show_id => "12345678", search_term => "fun", :status => "on_the_air", :sort_by => "air_date"})
+  
+  puts "There are a total of #{response.total} episodes matching the query"
+  
+  # For each episode display the episode's name and embed code for the default player.
+  response.episodes.each do |episode|
+    puts episode.name
+    default_player = episode.players.detect {|p| p.default}
+    puts default_player.embed_code
+  end
+
+To create a new episode:
+  
+  # Create the episode and tell Episodic about the video file and thumbnail file to use
+  response = ::Episodic::Platform::WriteMethods.create_episode("oz04s1q0i29t", "My Episode", {:air_date => Time.now + 1.week, :upload_types => "s3", :video_filename => "my_video.mp4", :thumbnail_filename => "my_thumb.png"})
+  
+  # Now upload the video and thumbnail.  It is best to upload the thumbnail first since it is usually smaller.
+  ::Episodic::Platform::WriteMethods.upload_file_for_episode(response.upload_for_filepath("/home/viceos/my_thumb.png"))
+  ::Episodic::Platform::WriteMethods.upload_file_for_episode(response.upload_for_filepath("/home/viceos/my_video.mp4"))
+  
+== HANDLING ERRORS:
+  
+Any errors returned from the Episodic Platform API are converted to exceptions and raised from the called method. For example,
+the following response would cause <tt>Episodic::Platform::InvalidAPIKey</tt> to be raised.
+
+  <?xml version="1.0" encoding="UTF-8"?>
+  <error>
+    <code>1</code>
+    <message>Invalid API Key</message>
+  </error>
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2010 Episodic, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,45 @@
+require 'rubygems'
+gem 'hoe', '>= 2.1.0'
+require 'hoe'
+require 'fileutils'
+require './lib/episodic/platform'
+
+Hoe.plugin :newgem
+# Hoe.plugin :website
+# Hoe.plugin :cucumberfeatures
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.spec 'episodic-platform' do
+  self.developer 'Randy Simon', 'support@episodic.com'
+  self.post_install_message = 'PostInstall.txt' # TODO remove if post-install message not required
+  self.rubyforge_name       = self.name # TODO this is default value
+  self.version              = '0.9'
+
+end
+
+require 'newgem/tasks'
+Dir['tasks/**/*.rake'].each { |t| load t }
+
+gem 'rdoc'
+gem 'hanna'
+require 'rake/rdoctask'
+require 'hanna/rdoctask'
+
+desc 'Generate RDoc documentation'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+#  rdoc.rdoc_files.include('README.rdoc', 'LICENSE', 'CHANGELOG').
+#    include('lib/**/*.rb').
+##    exclude('lib/will_paginate/named_scope*').
+
+  rdoc.main = "README.rdoc" # page to start on
+  rdoc.title = "Episodic Platform GEM documentation"
+
+  rdoc.rdoc_dir = 'doc' # rdoc output folder
+#  rdoc.options << '--webcvs=http://github.com/mislav/will_paginate/tree/master/'
+end
+
+
+# TODO - want other tests/tasks run by default? Add them to the list
+# remove_task :default
+# task :default => [:spec, :features]

data/lib/episodic/platform.rb

@@ -0,0 +1,82 @@
+require 'time'
+require 'digest/sha1'
+require 'digest/md5'
+require 'net/http'
+require 'uri'
+require 'zlib'
+
+def require_library_or_gem(library, gem_name = nil)
+  if RUBY_VERSION >= '1.9'
+    gem(gem_name || library, '>=0') 
+  end
+  require library
+rescue LoadError => library_not_installed
+  begin
+    require 'rubygems'
+    require library
+  rescue LoadError
+    raise library_not_installed
+  end
+end
+
+$:.unshift(File.dirname(__FILE__)) unless
+$:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+require_library_or_gem 'curb' unless defined? Curb
+require_library_or_gem 'xmlsimple', 'xml-simple' unless defined? XmlSimple
+require_library_or_gem 'hanna', 'mislav-hanna' unless defined? Hanna
+
+class Class # :nodoc:
+  def cattr_reader(*syms)
+    syms.flatten.each do |sym|
+      class_eval(<<-EOS, __FILE__, __LINE__)
+        unless defined? @@#{sym}
+          @@#{sym} = nil
+        end
+
+        def self.#{sym}
+          @@#{sym}
+        end
+
+        def #{sym}
+          @@#{sym}
+        end
+      EOS
+    end
+  end
+  
+  def cattr_writer(*syms)
+    syms.flatten.each do |sym|
+      class_eval(<<-EOS, __FILE__, __LINE__)
+        unless defined? @@#{sym}
+          @@#{sym} = nil
+        end
+
+        def self.#{sym}=(obj)
+          @@#{sym} = obj
+        end
+
+        def #{sym}=(obj)
+          @@#{sym} = obj
+        end
+      EOS
+    end
+  end
+  
+  def cattr_accessor(*syms)
+    cattr_reader(*syms)
+    cattr_writer(*syms)
+  end
+end if Class.instance_methods(false).grep(/^cattr_(?:reader|writer|accessor)$/).empty?
+
+require 'platform/exceptions'
+require 'platform/response'
+require 'platform/collection_response'
+require 'platform/connection'
+require 'platform/base'
+require 'platform/analytics_methods'
+require 'platform/query_methods'
+require 'platform/write_methods'
+
+Episodic::Platform::Base.class_eval do
+  include Episodic::Platform::Connection::Management
+end

data/lib/episodic/platform/analytics_methods.rb

@@ -0,0 +1,190 @@
+module Episodic #:nodoc:
+  
+  module Platform
+    
+    #
+    # Class for making requests against the Episodic Platform Analytics API.
+    #
+    class AnalyticsMethods < Base 
+      
+      class << self
+        
+        #
+        # Fetches a previously generated report.
+        #
+        # ==== Parameters
+        #
+        # report_token<String>:: This is the value returned from one of the report generation methods.
+        #
+        # ==== Returns
+        #
+        # String:: The contents of the report.
+        #
+        def get_report token
+          params = {
+            :report_token => token,
+          }
+          
+          response = connection.do_get(construct_url("analytics", "get_report"), params)
+          
+          return response.body
+        end
+        
+        #
+        # Generates a report for all episodes in a show. The report will contain information such as 
+        # the total views, complete views, downloads, etc for each episode in the show.
+        #
+        # It is important to note that this method just generates the report and returns a token
+        # that can be used to get the report by calling <tt>Episodic::Platform::AnalyticsMethods.get_report</tt>.
+        #
+        # ==== Parameters
+        #
+        # show_id<String>:: The id of the show that contains your episodes.  To get a list of your 
+        #    shows see <tt>Episodic::Platform::QueryMethods.show</tt>. 
+        # date_range<String>:: Specifies period of your report. The value of this parameter must be one 
+        #    of 'today', 'last_seven', 'last_thirty'.
+        # date_grouping<String>:: Must be one of 'daily' or 'aggregate' to list the data by day or just a total 
+        #    for the entire period respectively.
+        # format<String>:: The format parameter is required and must be one of 'csv' or 'xml'.
+        #
+        # ==== Returns
+        #
+        # Episodic::Platform::TokenResponse:: This response object includes a token that can be used to 
+        #    actually get the report by calling <tt>Episodic::Platform::AnalyticsMethods.get_report</tt>.
+        #
+        def episodes_summary_report show_id, date_range, date_grouping, format
+          
+          params = {
+            :show_id => show_id,
+            :date_range => date_range,
+            :date_grouping => date_grouping,
+            :format => format
+          }
+          
+          response = connection.do_get(construct_url("analytics", "request_episodes_summary_report"), params)
+          
+          # Convert to a hash
+          return parse_token_response(response)
+        end
+
+        #
+        # Generates a report for a specific episode in a show. The report will contain information 
+        # such as the total views, complete views, downloads, etc for each episode in the show. 
+        #
+        # It is important to note that this method just generates the report and returns a token
+        # that can be used to get the report by calling <tt>Episodic::Platform::AnalyticsMethods.get_report</tt>.
+        #
+        # ==== Parameters
+        #
+        # show_id<String>:: The id of the show that contains your episodes.  To get a list of your 
+        #    shows see <tt>Episodic::Platform::QueryMethods.show</tt>. 
+        # episode_id<String>:: The id of the episodes to generate the report for.  To get a list of your
+        #    episodes see <tt>Episodic::Platform::QueryMethods.episodes</tt>.
+        # date_range<String>:: Specifies period of your report. The value of this parameter must be one 
+        #    of 'today', 'last_seven', 'last_thirty'.
+        # format<String>:: The format parameter is required and must be one of 'csv' or 'xml'.
+        #
+        # ==== Returns
+        #
+        # Episodic::Platform::TokenResponse:: This response object includes a token that can be used to 
+        #    actually get the report by calling <tt>Episodic::Platform::AnalyticsMethods.get_report</tt>.
+        #
+        def episode_daily_report show_id, episode_id, date_range, format
+          
+          params = {
+            :show_id => show_id,
+            :date_range => date_range,
+            :id => episode_id,
+            :format => format
+          }
+          
+          response = connection.do_get(construct_url("analytics", "request_episode_daily_report"), params)
+          
+          # Convert to a hash
+          return parse_token_response(response)
+        end
+
+        #
+        # Generates a report for all campaigns in a specific show. The report will contain information 
+        # such as the total views, complete views, downloads, click throughs, etc for each campaign in the show. 
+        #
+        # It is important to note that this method just generates the report and returns a token
+        # that can be used to get the report by calling <tt>Episodic::Platform::AnalyticsMethods.get_report</tt>.
+        #
+        # ==== Parameters
+        #
+        # show_id<String>:: The id of the show that contains your campaigns.  To get a list of your 
+        #    shows see <tt>Episodic::Platform::QueryMethods.show</tt>. 
+        # date_range<String>:: Specifies period of your report. The value of this parameter must be one 
+        #    of 'today', 'last_seven', 'last_thirty'.
+        # format<String>:: The format parameter is required and must be one of 'csv' or 'xml'.
+        #
+        # ==== Returns
+        #
+        # Episodic::Platform::TokenResponse:: This response object includes a token that can be used to 
+        #    actually get the report by calling <tt>Episodic::Platform::AnalyticsMethods.get_report</tt>.
+        #
+        def campaigns_daily_report show_id, date_range, format
+          
+          params = {
+            :show_id => show_id,
+            :date_range => date_range,
+            :format => format
+          }
+          
+          response = connection.do_get(construct_url("analytics", "request_campaigns_daily_report"), params)
+          
+          # Convert to a hash
+          return parse_token_response(response)
+        end
+        
+        protected
+        
+        #
+        # Method factored out to make unit testing easier.  This method simply creates the <tt>::Episodic::Platform::TokenResponse</tt>
+        # object.
+        #
+        # ==== Parameters
+        #
+        # response<Episodic::Platform::HTTPResponse>:: The response from any token request
+        #
+        # ==== Returns
+        #
+        # ::Episodic::Platform::TokenResponse:: The parsed response.
+        #
+        def parse_token_response response
+          return TokenResponse.new(response)
+        end
+      end
+    end
+    
+    #
+    # All token request methods have a similar response structure.  This class extends <tt>Episodic::Platform::Response</tt>
+    # and adds a method to get the token of the generated report.
+    #
+    class TokenResponse < Response
+      
+      #
+      # Constructor
+      #
+      # ==== Parameters
+      #
+      # response<Episodic::Platform::HTTPResponse>:: The response object returned from an Episodic Platform API request.
+      #
+      def initialize response
+        super(response, "ForceArray" => false)
+      end
+      
+      #
+      # Get the token used to request the generated report.  This token is passed to 
+      # <tt>Episodic::Platform::AnalyticsMethods.get_report</tt>.
+      #
+      def token
+        return @parsed_body["report_token"]
+      end
+      
+    end
+    
+  end
+  
+end