slaskis-fleakr 0.5.0

data/lib/fleakr/api.rb

@@ -0,0 +1,8 @@
+require "fleakr/api/response"
+require "fleakr/api/method_request"
+require "fleakr/api/option"
+require "fleakr/api/upload_request"
+require "fleakr/api/parameter_list"
+require "fleakr/api/parameter"
+require "fleakr/api/value_parameter"
+require "fleakr/api/file_parameter"

data/lib/fleakr/api/file_parameter.rb

@@ -0,0 +1,47 @@
+module Fleakr
+  module Api # :nodoc:
+    
+    # = FileParameter
+    #
+    # Parameter class to encapsulate file data sent to the Flickr upload API
+    #
+    class FileParameter < Parameter
+      
+      MIME_TYPES = {
+        '.jpg' => 'image/jpeg',
+        '.png' => 'image/png',
+        '.gif' => 'image/gif'
+      }
+      
+      # Create a parameter with name and specified filename
+      #
+      def initialize(name, filename)
+        @filename = filename
+        super(name, false)
+      end
+      
+      # Discover MIME type by file extension using MIME_TYPES constant
+      #
+      def mime_type
+        MIME_TYPES[File.extname(@filename)]
+      end
+      
+      # File data (from @filename) to pass to the Flickr API
+      # 
+      def value
+        @value ||= File.read(@filename)
+      end
+      
+      # Generate a form representation of this file for upload (as multipart/form-data)
+      #
+      def to_form
+        "Content-Disposition: form-data; name=\"#{self.name}\"; filename=\"#{@filename}\"\r\n" +
+        "Content-Type: #{self.mime_type}\r\n" +
+        "\r\n" +
+        "#{self.value}\r\n"
+      end
+      
+    end
+    
+  end
+end

data/lib/fleakr/api/method_request.rb

@@ -0,0 +1,66 @@
+module Fleakr
+  module Api # :nodoc:
+    
+    # = MethodRequest
+    # 
+    # Handles all API requests that are non-upload related.  For upload requests see the
+    # UploadRequest class.
+    #
+    class MethodRequest
+      attr_reader :parameters, :method
+      
+      # Makes a request to the Flickr API and returns a valid Response object.  If
+      # there are errors on the response it will raise an ApiError exception.  See 
+      # MethodRequest#new for details about the additional parameters
+      #
+      def self.with_response!(method, additional_parameters = {})
+        request = self.new(method, additional_parameters)
+        response = request.send
+
+        raise(Fleakr::ApiError, "Code: #{response.error.code} - #{response.error.message}") if response.error?
+
+        response
+      end
+      
+      # Create a new request for the specified API method and pass along any additional
+      # parameters.  The Flickr API uses namespacing for its methods - this is optional
+      # when calling this method.
+      #
+      # This must be called after initializing the library with the required API key
+      # see (#Fleakr.api_key=)
+      #
+      # The <tt>additional_parameters</tt> is a list of parameters to pass directly to 
+      # the Flickr API call.  The exception to this is the <tt>:authenticate?</tt> option
+      # that will force the call to not be authenticated if it is set to false (The default
+      # behavior is to authenticate all calls when we have a token).
+      #
+      def initialize(method, additional_parameters = {})
+        @parameters = ParameterList.new(additional_parameters)
+        
+        self.method = method
+      end
+   
+      def method=(method) # :nodoc:
+        @method = method.sub(/^(flickr\.)?/, 'flickr.')
+        @parameters << ValueParameter.new('method', @method)
+      end
+
+      def send # :nodoc:
+        logger.info("Sending request to: #{endpoint_uri}")
+        response_xml = Net::HTTP.get(endpoint_uri)
+        logger.debug("Response data:\n#{response_xml}")
+        
+        Response.new(response_xml)
+      end
+      
+      private
+      def endpoint_uri
+        uri = URI.parse('http://api.flickr.com/services/rest/')
+        uri.query = self.parameters.to_query
+        uri
+      end
+      
+    end
+    
+  end
+end

data/lib/fleakr/api/option.rb

@@ -0,0 +1,175 @@
+module Fleakr
+  module Api # :nodoc:
+
+    # = Option
+    #
+    # Top-level class for creating specific option instances based on type
+    #
+    class Option
+      
+      MAPPING = {
+        :tags        => 'TagOption',
+        :viewable_by => 'ViewOption',
+        :level       => 'LevelOption',
+        :type        => 'TypeOption',
+        :hide?       => 'HiddenOption'
+      }
+      
+      # Initialize a new option for the specified type and value
+      #
+      def self.for(type, value)
+        class_for(type).new(type, value)
+      end
+      
+      def self.class_for(type) # :nodoc:
+        class_name = MAPPING[type] || 'SimpleOption'
+        "Fleakr::Api::#{class_name}".constantize
+      end
+      
+    end
+    
+    # = SimpleOption
+    # 
+    # Simple name / value option pair
+    #
+    class SimpleOption
+
+      attr_reader :type, :value
+     
+      # Create an option of the specified type and value
+      #
+      def initialize(type, value)
+        @type  = type
+        @value = value
+      end
+      
+      # Generate hash representation of this option
+      #
+      def to_hash
+        {type => value}
+      end
+      
+    end
+    
+    # = TagOption
+    #
+    # Represents values for tags
+    #
+    class TagOption < SimpleOption
+      
+      # Tag with specified values.  Value passed will be converted to an array if it isn't
+      # already
+      # 
+      def initialize(type, value)
+        super type, value
+        @value = Array(self.value)
+      end
+    
+      # Hash representation of tag values (separated by spaces).  Handles multi-word tags 
+      # by enclosing each tag in double quotes.
+      #
+      def to_hash
+        tags = value.map {|tag| "\"#{tag}\"" }
+        {type => tags.join(' ')}
+      end
+      
+    end
+    
+    # = ViewOption
+    #
+    # Specify who is able to view the photo.
+    #
+    class ViewOption < SimpleOption
+      
+      # Specify who this is viewable by (e.g. everyone / friends / family).
+      #
+      def initialize(type, value)
+        super type, Array(value)
+      end
+      
+      # Is this publicly viewable? (i.e. :everyone)
+      #
+      def public?
+        value == [:everyone]
+      end
+      
+      # Is this viewable by friends? (i.e. :friends)
+      #
+      def friends?
+        value.include?(:friends)
+      end
+
+      # Is this viewable by family? (i.e. :family)
+      #
+      def family?
+        value.include?(:family)
+      end
+      
+      # Hash representation of photo permissions
+      #
+      def to_hash
+        {:is_public => public?.to_i, :is_friend => friends?.to_i, :is_family => family?.to_i}
+      end
+      
+    end
+    
+    # = LevelOption
+    #
+    # Specify the "safety level" of this photo (e.g. safe / moderate / restricted)
+    #
+    class LevelOption < SimpleOption
+     
+      def value # :nodoc: 
+        case @value
+          when :safe        then 1
+          when :moderate    then 2
+          when :restricted  then 3
+        end
+      end
+      
+      # Hash representation of the safety_level for this photo
+      #
+      def to_hash
+        {:safety_level => value}
+      end
+      
+    end
+    
+    # = TypeOption
+    #
+    # Specify the type of this photo (e.g. photo / screenshot / other)
+    #
+    class TypeOption < SimpleOption
+      
+      def value # :nodoc:
+        case @value
+          when :photo       then 1
+          when :screenshot  then 2
+          when :other       then 3
+        end
+      end
+      
+      # Hash representation of this type
+      #
+      def to_hash
+        {:content_type => value}
+      end
+      
+    end
+    
+    # = HiddenOption
+    #
+    # Specify whether this photo should be hidden from search
+    #
+    class HiddenOption < SimpleOption
+     
+      # Hash representation of whether to hide this photo
+      #
+      def to_hash
+        {:hidden => (value ? 2 : 1)}
+      end
+      
+    end
+
+  end
+end

data/lib/fleakr/api/parameter.rb

@@ -0,0 +1,35 @@
+module Fleakr
+  module Api # :nodoc:
+
+    # = Parameter
+    # 
+    # Base class for other parameters that get passed to the Flickr API - see
+    # #FileParameter and #ValueParameter for examples
+    #
+    class Parameter
+     
+      attr_reader :name
+     
+      # A new named parameter (never used directly)
+      #
+      def initialize(name, include_in_signature = true)
+        @name                 = name
+        @include_in_signature = include_in_signature
+      end
+      
+      # Should this parameter be used when generating the signature?
+      #
+      def include_in_signature?
+        (@include_in_signature == true) ? true : false
+      end
+      
+      # Used for sorting when generating a signature
+      #
+      def <=>(other)
+        self.name <=> other.name
+      end
+      
+    end
+    
+  end
+end

data/lib/fleakr/api/parameter_list.rb

@@ -0,0 +1,97 @@
+module Fleakr
+  module Api # :nodoc:
+    
+    # = ParameterList
+    #
+    # Represents a list of parameters that get passed as part of a
+    # MethodRequest or UploadRequest.  These can be transformed as necessary
+    # into query strings (using #to_query) or form data (using #to_form)
+    #
+    class ParameterList
+      
+      # Create a new parameter list with optional parameters:
+      # [:authenticate?] Request will automatically be authenticated if Fleakr.token is available
+      #                  set this to false to force it not to authenticate
+      #
+      # Any additional name / value pairs will be created as individual 
+      # ValueParameters as part of the list.  Example:
+      #
+      #   >> list = Fleakr::Api::ParameterList.new(:foo => 'bar')
+      #   => #<Fleakr::Api::ParameterList:0x1656e6c @list=... >
+      #   >> list[:foo]
+      #   => #<Fleakr::Api::ValueParameter:0x1656da4 @include_in_signature=true, @name="foo", @value="bar">
+      #
+      def initialize(options = {})
+        # TODO: need to find a way to move the unexpected behavior in Fleakr.token elsewhere
+        @api_options = options.extract!(:authenticate?)
+        
+        @list = Hash.new
+
+        options.each {|k,v| self << ValueParameter.new(k.to_s, v) }
+
+        self << ValueParameter.new('api_key', Fleakr.api_key)
+        self << ValueParameter.new('auth_token', Fleakr.token.value) if authenticate?
+      end
+      
+      # Add a new parameter (ValueParameter / FileParameter) to the list
+      #
+      def <<(parameter)
+        @list.merge!(parameter.name => parameter)
+      end
+      
+      # Should this parameter list be signed?
+      #
+      def sign?
+        !Fleakr.shared_secret.blank?
+      end
+      
+      # Should we send the auth_token with the request?
+      #
+      def authenticate?
+        @api_options.has_key?(:authenticate?) ? @api_options[:authenticate?] : !Fleakr.token.blank?
+      end
+      
+      # Access an individual parameter by key (symbol or string)
+      #
+      def [](key)
+        list[key.to_s]
+      end
+      
+      def boundary # :nodoc:
+        @boundary ||= Digest::MD5.hexdigest(rand.to_s)
+      end
+      
+      # Generate the query string representation of this parameter 
+      # list - e.g. <tt>foo=bar&blee=baz</tt>
+      #
+      def to_query
+        list.values.map {|element| element.to_query }.join('&')
+      end
+      
+      # Generate the form representation of this parameter list including the
+      # boundary
+      #
+      def to_form
+        form = list.values.map {|p| "--#{self.boundary}\r\n#{p.to_form}" }.join
+        form << "--#{self.boundary}--"
+
+        form
+      end
+      
+      def signature # :nodoc:
+        parameters_to_sign = @list.values.reject {|p| !p.include_in_signature? }
+        signature_text = parameters_to_sign.sort.map {|p| "#{p.name}#{p.value}" }.join
+
+        Digest::MD5.hexdigest("#{Fleakr.shared_secret}#{signature_text}")
+      end
+      
+      private
+      def list
+        list = @list
+        list.merge!('api_sig' => ValueParameter.new('api_sig', signature, false)) if self.sign?
+        
+        list
+      end
+    end
+  end
+end

data/lib/fleakr/api/response.rb

@@ -0,0 +1,35 @@
+module Fleakr
+  module Api # :nodoc:
+    
+    # = Response
+    #
+    # Response objects contain Hpricot documents that are traversed and parsed by
+    # the model objects.  This class is never called directly but is instantiated
+    # during the request cycle (see: Fleakr::Api::MethodRequest.with_response!)
+    #
+    class Response
+
+      # Creates a new response from a raw XML string returned from a Request
+      def initialize(response_xml)
+        @response_xml = response_xml
+      end
+
+      # Return a document-based representation of the XML contained in the
+      # API response.  This is an Hpricot document object
+      def body
+        @body ||= Hpricot.XML(@response_xml)
+      end
+
+      # Did the response from the API contain errors?
+      def error?
+        (self.body/'rsp').attr('stat') != 'ok'
+      end
+
+      # Access the API error if one exists
+      def error
+        Fleakr::Objects::Error.new(self.body) if self.error?
+      end
+
+    end
+  end
+end