episodic-platform 0.9

data/lib/episodic/platform/base.rb

@@ -0,0 +1,64 @@
+module Episodic #:nodoc:
+  
+  #
+  # Episodic::Platform is a Ruby library for Episodic's Platform REST API (http://app.episodic.com/help/server_api)
+  #
+  # == 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')
+  #
+  # == 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>
+  #
+  module Platform
+    API_HOST = 'app.episodic.com'
+    API_VERSION = 'v2'
+    
+    #
+    # Episodic::Platform::Base is the abstract super class of all classes who make requests against the Episodic Platform REST API.
+    #
+    # Establishing a connection with the Base class is the entry point to using the library:
+    #
+    #   Episodic::Platform::Base.establish_connection!('my_api_key', 'my_secret_key')
+    #
+    class Base 
+      
+      class << self
+        
+        #
+        # Helper method to construct an Episodic Platform API request URL.
+        #
+        # ==== Parameters
+        #
+        # api_name<String>:: Specifies the API you are calling.  Examples are "write", query" and "analytics"
+        # method_name<String>:: The method being invoked.
+        #
+        # ==== Returns
+        #
+        # URI:: The constructed URL.
+        #
+        def construct_url api_name, method_name
+          return URI.parse("http://#{connection.connection_options[:api_host] || API_HOST}/api/#{API_VERSION}/#{api_name}/#{method_name}")
+        end
+        
+      end
+      
+    end
+  end
+  
+end

data/lib/episodic/platform/collection_response.rb

@@ -0,0 +1,45 @@
+module Episodic
+  
+  module Platform
+    
+    #
+    # Base class for responses that return an collection of objects.
+    #
+    class CollectionResponse < Response
+      
+      COLLECTION_RESPONSE_ATTRIBUTES = [:page, :pages, :total, :per_page]
+      
+      #
+      # Constructor
+      #
+      # ==== Parameters
+      #
+      # response<Episodic::Platform::HttpResponse>:: The response object returned from an Episodic Platform API request.
+      # xml_options<Hash>:: A set of options used by XmlSimple when parsing the response body
+      #
+      def initialize response, xml_options = {}
+        super(response, xml_options)
+      end
+      
+      #
+      # Override to look up attributes by name
+      #
+      def method_missing(method_sym, *arguments, &block)
+        method_name = method_sym.to_s
+        if (COLLECTION_RESPONSE_ATTRIBUTES.include?(method_sym))
+          return @parsed_body[method_name].to_i
+        end
+        
+        return super
+      end
+      
+      #
+      # Attributes can be accessed as methods.
+      #
+      def respond_to?(symbol, include_private = false)
+        return COLLECTION_RESPONSE_ATTRIBUTES.include?(symbol)
+      end
+      
+    end
+  end
+end

data/lib/episodic/platform/connection.rb

@@ -0,0 +1,305 @@
+module Episodic
+  module Platform
+    
+    #
+    # Class used to make the actual requests to the Episodic Platform API.
+    #
+    class Connection
+      
+      attr_reader :episodic_api_key, :episodic_secret_key, :connection_options
+      
+      #
+      # Constructor
+      #
+      # episodic_api_key<String>:: The caller's Episodic API Key
+      # episodic_secret_key<String>:: The caller's Episodic Secret Key
+      # options<Hash>:: Used mostly for testing by allowing the caller to override some constants such 
+      #   the API host.
+      #
+      def initialize(episodic_api_key, episodic_secret_key, options = {})
+        @episodic_api_key = episodic_api_key
+        @episodic_secret_key = episodic_secret_key
+        @connection_options = options
+      end     
+      
+      #
+      # Perform the POST request to the specified URL.  This method takes the params passed in and
+      # generates the signature parameter using the Episodic Secret Key for this connection.  The 
+      # signature, the Episodic API Key for this connection and the passed in params are then used to
+      # generate the form post.  
+      #
+      # If there are any filenames passed then these are also included in the form post.
+      #
+      # ==== Parameters
+      #
+      # url<URI>:: The URL to the Episodic Platform API endpoint
+      # params<Hash>:: A hash of parameters to include include in the post request.
+      # file_params<Hash>:: A hash of file parameters. The name is the parameter name and value is the path to the file.
+      #
+      # ==== Returns
+      #
+      # Episodic::Platform::HTTPResponse:: The full response object.
+      #
+      def do_post url, params, file_params = nil
+        
+        # Convert all the params to strings
+        request_params = convert_params_for_request(params)
+        
+        # Add in the common params
+        append_common_params(request_params)
+        
+        c = Curl::Easy.new(url.to_s)  
+        c.multipart_form_post = true
+        
+        fields = []
+        request_params.each_pair do |name, value|
+          fields << Curl::PostField.content(name, value)
+        end
+        file_params.each do |name, value|
+          fields << Curl::PostField.file(name, value) 
+        end unless file_params.nil?
+        
+        # Make the request
+        c.http_post(*fields)
+        
+        return Episodic::Platform::HTTPResponse.new(c.response_code, c.body_str)
+      end
+      
+      #
+      # Perform the GET request to the specified URL.  This method takes the params passed in and
+      # generates the signature parameter using the Episodic Secret Key for this connection.  The 
+      # signature, the Episodic API Key for this connection and the passed in params are then used to
+      # generate the query string.
+      #
+      # ==== Parameters
+      #
+      # url<URI>:: The URL to the Episodic Platform API endpoint
+      # params<Hash>:: A hash of parameters to include include in the query string.
+      #
+      # ==== Returns
+      #
+      # Episodic::Platform::HTTPResponse:: The full response object.
+      #
+      def do_get url, params
+        
+        # Convert all the params to strings
+        request_params = convert_params_for_request(params)
+        
+        # Add in the common params
+        append_common_params(request_params)
+        
+        queryString = ""
+        request_params.keys.each_with_index do |key, index|
+          queryString << "#{index == 0 ? '?' : '&'}#{key}=#{::URI.escape(request_params[key])}"
+        end
+        
+        # Create the request
+        http = Net::HTTP.new(url.host, url.port)
+        response = http.start() {|req| req.get(url.path + queryString)}
+        
+        return Episodic::Platform::HTTPResponse.new(response.code, response.body)
+      end
+      
+      protected
+      
+      #
+      # Helper method to generate the request signature
+      #
+      # ==== Parameters
+      #
+      # params<Hash>:: The set of params that will be passed either in the form post or in the 
+      #    query string.
+      #
+      def generate_signature_from_params params
+        sorted_keys = params.keys.sort {|x,y| x.to_s <=> y.to_s }
+        string_to_sign = @episodic_secret_key
+        sorted_keys.each do |key|
+          string_to_sign += "#{key.to_s}=#{params[key]}"
+        end
+        
+        return Digest::SHA256.hexdigest(string_to_sign) 
+      end
+      
+      #
+      # Apply the common Episodic params such as expires, signature and key
+      #
+      # ==== Parameters
+      #
+      # params<Hash>:: The params to update.
+      #
+      def append_common_params params
+        
+        # Add an expires value if it has not been added already
+        params["expires"] ||= (Time.now.to_i + 30).to_s
+        
+        # Sign the request
+        params["signature"] = self.generate_signature_from_params(params)
+        
+        # Add our key
+        params["key"] = @episodic_api_key        
+      end
+      
+      #
+      # Converts all parameters to a form for a request.  This includes converting arrays to comma delimited strings,
+      # Times to integers and Hashes to a form depending on its level in the passed in params.
+      #
+      # ==== Parameters
+      #
+      # params<Hash>:: The params to convert.
+      #
+      # ==== Returns
+      #
+      # Hash:: A single level hash where all keys and values are strings.
+      #
+      def convert_params_for_request params
+        result = {}
+        
+        params.each_pair do |key, value|
+          
+          # We don't want to deal with nils
+          value = "" if value.nil?
+          
+          if value.is_a?(Array)
+            # Convert to a comma delimited string
+            result[key.to_s] = value.join(",")
+          elsif value.is_a?(Time)
+            #Convert the time to an integer (then string)
+            result[key.to_s] = value.to_i.to_s
+          elsif value.is_a?(Hash)
+            # Used for custom fields
+            value.each_pair do |sub_key, sub_value|
+              sub_value = "" if sub_value.nil?
+              if (sub_value.is_a?(Time))
+                result["#{key.to_s}[#{sub_key.to_s}]"] = sub_value.to_i.to_s
+              elsif (sub_value.is_a?(Hash))
+                # Put the hash in the external select field form
+                val = ""
+                sub_value.each_pair do |k, v|
+                  val << "#{k}|#{v};"
+                end
+                result["#{key.to_s}[#{sub_key.to_s}]"] = val
+              else
+                result["#{key.to_s}[#{sub_key.to_s}]"] = sub_value.to_s
+              end
+            end 
+          else
+            result[key.to_s] = value.to_s 
+          end
+        end
+        
+        return result
+      end
+      
+      module Management #:nodoc:
+        def self.included(base)
+          base.cattr_accessor :connections
+          base.connections = {}
+          base.extend ClassMethods
+        end
+        
+        #
+        # Manage the creation and destruction of connections for Episodic::Platform::Base and its subclasses. Connections are
+        # created with establish_connection!.
+        #
+        module ClassMethods
+          
+          #
+          # Creates a new connection with which to make requests to the Episodic Platform for the 
+          # calling class.
+          #   
+          #   Episodic::Platform::Base.establish_connection!(episodic_api_key, episodic_secret_key)
+          #
+          # You can set connections for every subclass of Episodic::Platform::Base. Once the initial 
+          # connection is made on Base, all subsequent connections will inherit whatever values you 
+          # don't specify explictly.
+          #
+          # ==== Parameters
+          #
+          # episodic_api_key<String>:: This is your Episodic API Key
+          # episodic_secret_key<String>:: This is your Episodic Secret Key
+          #
+          def establish_connection!(episodic_api_key, episodic_secret_key, options = {})
+            connections[connection_name] = Connection.new(episodic_api_key, episodic_secret_key, options)
+          end
+          
+          #
+          # Returns the connection for the current class, or Base's default connection if the current class does not
+          # have its own connection.
+          #
+          # If not connection has been established yet, NoConnectionEstablished will be raised.
+          #
+          # ==== Returns
+          #
+          # Episodic::Platform::Connection:: The connection for the current class or the default connection
+          #
+          def connection
+            if connected?
+              connections[connection_name] || default_connection
+            else
+              raise NoConnectionEstablished
+            end
+          end
+          
+          #
+          # Returns true if a connection has been made yet.
+          #
+          # ==== Returns
+          #
+          # Boolean:: <tt>true</tt> if there is at least one connection
+          #
+          def connected?
+            !connections.empty?
+          end
+          
+          #
+          # Removes the connection for the current class. If there is no connection for the current class, the default
+          # connection will be removed.
+          #
+          # ==== Parameters
+          #
+          # name<String>:: The name of the connection.  This defaults to the default connection name.
+          #
+          def disconnect(name = connection_name)
+            name       = default_connection unless connections.has_key?(name)
+            connections.delete(name)
+          end
+          
+          #
+          # Removes all connections 
+          #
+          def disconnect!
+            connections.each_key {|connection| disconnect(connection)}
+          end
+          
+          private
+          
+          #
+          # Get the name of this connection
+          #
+          # ==== Returns
+          #
+          # String:: The connection name
+          #
+          def connection_name
+            name
+          end
+          
+          #
+          # Hardcoded default connection name
+          #
+          def default_connection_name
+              'Episodic::Platform::Base'
+          end
+          
+          #
+          # Shortcut to get the default connection
+          #
+          def default_connection
+            connections[default_connection_name]
+          end
+        end
+      end
+      
+    end
+  end
+end

data/lib/episodic/platform/exceptions.rb

@@ -0,0 +1,105 @@
+module Episodic
+  module Platform
+    
+    #
+    # Abstract super class of all Episodic::Platform exceptions
+    #
+    class EpisodicPlatformException < StandardError
+    end
+    
+    class FileUploadFailed < EpisodicPlatformException  
+    end
+    
+    #
+    # An execption that is raised as a result of the response content.
+    #
+    class ResponseError < EpisodicPlatformException
+      
+      attr_reader :response
+      
+      #
+      # Constructor
+      #
+      # ==== Parameters
+      #
+      # message<String>:: The message to include in the exception
+      # response<Episodic::Platform::HTTPResponse>:: The response object.
+      #
+      def initialize(message, response)
+        @response = response
+        super(message)
+      end
+    end
+    
+    #
+    # There was an unexpected error on the server. .
+    #
+    class InternalError < ResponseError
+    end
+
+    #
+    # The API Key wasn't provided or is invalid or the signature is invalid.
+    #    
+    class InvalidAPIKey < ResponseError
+    end
+
+    #
+    # The requested report could not be found. Either the report token is invalid or the report has expired and is no longer available.
+    #  
+    class ReportNotFound < ResponseError
+    end
+    
+    #
+    # The request failed to specifiy one or more of the required parameters to an API method. 
+    # 
+    class MissingRequiredParameter < ResponseError
+    end
+
+    #
+    # The request is no longer valid because the expires parameter specifies a time that has passed. 
+    #
+    class RequestExpired < ResponseError
+    end
+    
+    #
+    # The specified object (i.e. show, episode, etc.) could not be found.  
+    #
+    class NotFound < ResponseError
+    end
+    
+    #
+    # API access for the user is disabled.   
+    #
+    class APIAccessDisabled < ResponseError
+    end
+    
+    #
+    # The value specified for a parameter is not valid.    
+    #
+    class InvalidParameters < ResponseError
+      
+      #
+      # Constructor.  Override to include inforation about the invalid parameter(s).
+      #
+      # ==== Parameters
+      #
+      # message<String>:: The message to include in the exception
+      # response<Episodic::Platform::HTTPResponse>:: The response object.
+      # invalid_parameters<Object>:: This is either a Hash or an Array of hashes if there is more than one invalid parameter.
+      #
+      def initialize(message, response, invalid_parameters)
+        
+        if (invalid_parameters)
+          invalid_parameters["invalid_parameter"] = [invalid_parameters["invalid_parameter"]] if invalid_parameters["invalid_parameter"].is_a?(Hash)
+          
+          # Append to the message
+          invalid_parameters["invalid_parameter"].each do |ip|
+            message << "\n#{ip['name']}: #{ip['content']}"
+          end
+        end
+        
+        super(message, response)
+      end
+    end
+  end
+end