reagent-fleakr 0.3.0 → 0.4.0

data/lib/fleakr/api/parameter_list.rb

@@ -0,0 +1,96 @@
+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:
+      # [:sign?] Will these parameters be used to sign the request?
+      # [:authenticate?] Will the request need to be authenticated?
+      #
+      # 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 = {})
+        @api_options = options.extract!(:sign?, :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?
+        (@api_options[:sign?] == true || authenticate?) ? true : false
+      end
+      
+      # Should we send the auth_token with the request?
+      #
+      def authenticate?
+        (@api_options[:authenticate?] == true) ? true : false
+      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(&: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

@@ -1,11 +1,11 @@
 module Fleakr
-  module Api
+  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::Request.with_response!)
+    # during the request cycle (see: Fleakr::Api::MethodRequest.with_response!)
     #
     class Response
 

data/lib/fleakr/api/upload_request.rb

@@ -0,0 +1,64 @@
+module Fleakr
+  module Api # :nodoc:
+    
+    # = UploadRequest
+    # 
+    # This implements the upload functionality of the Flickr API which is needed
+    # to create new photos and replace the photo content of existing photos
+    #
+    class UploadRequest
+
+      ENDPOINT_URIS = {
+        :create => 'http://api.flickr.com/services/upload/',
+        :update => 'http://api.flickr.com/services/replace/'
+      }
+
+      attr_reader :parameters, :type
+
+      # Send a request and return a Response object.  If an API error occurs, this raises
+      # a Fleakr::ApiError with the reason for the error.  See UploadRequest#new for more 
+      # details.
+      #
+      def self.with_response!(filename, options = {})
+        request = self.new(filename, options)
+        response = request.send
+        
+        raise(Fleakr::ApiError, "Code: #{response.error.code} - #{response.error.message}") if response.error?
+
+        response
+      end
+      
+      # Create a new UploadRequest with the specified filename and options:
+      #
+      # [:type] Valid values are :create and :update and are used when uploading new 
+      #         photos or replacing existing ones
+      #
+      def initialize(filename, options = {})
+        type_options = options.extract!(:type)
+        options.merge!(:authenticate? => true)
+        
+        @type = type_options[:type] || :create
+        
+        @parameters = ParameterList.new(options)
+        @parameters << FileParameter.new('photo', filename)
+      end
+      
+      def headers # :nodoc:
+        {'Content-Type' => "multipart/form-data; boundary=#{self.parameters.boundary}"}
+      end
+
+      def send # :nodoc:
+        response = Net::HTTP.start(endpoint_uri.host, endpoint_uri.port) do |http| 
+          http.post(endpoint_uri.path, self.parameters.to_form, self.headers)
+        end
+        Response.new(response.body)
+      end
+      
+      private
+      def endpoint_uri
+        @endpoint_uri ||= URI.parse(ENDPOINT_URIS[self.type])
+      end
+    end
+    
+  end
+end

data/lib/fleakr/api/value_parameter.rb

@@ -0,0 +1,36 @@
+module Fleakr
+  module Api # :nodoc:
+    
+    # = ValueParameter
+    #
+    # A simple name / value parameter for use in API calls
+    #
+    class ValueParameter < Parameter
+      
+      attr_reader :value
+     
+      # Create a new parameter with the specified name / value pair.
+      #
+      def initialize(name, value, include_in_signature = true)
+        @value = value
+        super(name, include_in_signature)
+      end
+      
+      # Generate the query string representation of this parameter.
+      #
+      def to_query
+        "#{self.name}=#{CGI.escape(self.value.to_s)}"
+      end
+      
+      # Generate the form representation of this parameter.
+      #
+      def to_form
+        "Content-Disposition: form-data; name=\"#{self.name}\"\r\n" +
+        "\r\n" +
+        "#{self.value}\r\n"
+      end
+      
+    end
+    
+  end
+end

data/lib/fleakr/core_ext.rb

@@ -0,0 +1 @@
+require 'fleakr/core_ext/hash'

data/lib/fleakr/core_ext/hash.rb

@@ -0,0 +1,22 @@
+class Hash
+
+  # Extract the matching keys from the source hash and return
+  # a new hash with those keys:
+  #
+  #   >> h = {:a => 'b', :c => 'd'}
+  #   => {:a=>"b", :c=>"d"}
+  #   >> h.extract!(:a)
+  #   => {:a=>"b"}
+  #   >> h
+  #   => {:c=>"d"}
+  #
+  def extract!(*keys)
+    value = {}
+    
+    keys.each {|k| value.merge!({k => self[k]}) if self.has_key?(k) }
+    keys.each {|k| delete(k) }
+    
+    value
+  end
+  
+end

data/lib/fleakr/objects.rb

@@ -0,0 +1,9 @@
+require 'fleakr/objects/authentication_token'
+require 'fleakr/objects/contact'
+require 'fleakr/objects/error'
+require 'fleakr/objects/group'
+require 'fleakr/objects/image'
+require 'fleakr/objects/photo'
+require 'fleakr/objects/search'
+require 'fleakr/objects/set'
+require 'fleakr/objects/user'

data/lib/fleakr/objects/authentication_token.rb

@@ -0,0 +1,43 @@
+module Fleakr
+  module Objects # :nodoc:
+    
+    # = AuthenticationToken
+    #
+    # This class represents an authentication token used for API calls that 
+    # require authentication before they can be used
+    #
+    # == Attributes
+    #
+    # [value] The token value that is used in subsequent API calls
+    # [permissions] The permissions granted to this application (read / write / delete)
+    #
+    class AuthenticationToken
+      
+      include Fleakr::Support::Object
+      
+      flickr_attribute :value, :from => 'auth/token'
+      flickr_attribute :permissions, :from => 'auth/perms'
+      
+      # Retrieve a full authentication token from the supplied mini-token (e.g. 123-456-789)
+      #
+      def self.from_mini_token(token)
+        parameters = {:mini_token => token, :sign? => true}
+        response = Fleakr::Api::MethodRequest.with_response!('auth.getFullToken', parameters)
+        
+        self.new(response.body)
+      end
+      
+      # Retrieve a full authentication token from the supplied auth_token string
+      # (e.g. 45-76598454353455)
+      # 
+      def self.from_auth_token(token)
+        parameters = {:auth_token => token, :sign? => true}
+        response = Fleakr::Api::MethodRequest.with_response!('auth.checkToken', parameters)
+        
+        self.new(response.body)
+      end
+      
+    end
+    
+  end
+end

data/lib/fleakr/objects/contact.rb

@@ -4,15 +4,15 @@ module Fleakr
 
       include Fleakr::Support::Object
 
-      flickr_attribute :id, :attribute => 'nsid'
-      flickr_attribute :username, :attribute => 'username'
-      flickr_attribute :icon_server, :attribute => 'iconserver'
-      flickr_attribute :icon_farm, :attribute => 'iconfarm'
+      flickr_attribute :id, :from => '@nsid'
+      flickr_attribute :username
+      flickr_attribute :icon_server, :from => '@iconserver'
+      flickr_attribute :icon_farm,   :from => '@iconfarm'
 
       # Retrieve a list of contacts for the specified user ID and return an initialized
       # collection of #User objects
       def self.find_all_by_user_id(user_id)
-        response = Fleakr::Api::Request.with_response!('contacts.getPublicList', :user_id => user_id)
+        response = Fleakr::Api::MethodRequest.with_response!('contacts.getPublicList', :user_id => user_id)
         (response.body/'contacts/contact').map {|c| Contact.new(c).to_user }
       end
       

data/lib/fleakr/objects/error.rb

@@ -14,8 +14,8 @@ module Fleakr
 
       include Fleakr::Support::Object
 
-      flickr_attribute :code, :xpath => 'rsp/err', :attribute => 'code'
-      flickr_attribute :message, :xpath => 'rsp/err', :attribute => 'msg'
+      flickr_attribute :code, :from => 'err@code'
+      flickr_attribute :message, :from => 'err@msg'
 
     end
   end

data/lib/fleakr/objects/group.rb

@@ -12,8 +12,8 @@ module Fleakr
 
       include Fleakr::Support::Object
 
-      flickr_attribute :id, :attribute => 'nsid'
-      flickr_attribute :name, :attribute => 'name'
+      flickr_attribute :id, :from => '@nsid'
+      flickr_attribute :name
 
       find_all :by_user_id, :call => 'people.getPublicGroups', :path => 'groups/group'
 

data/lib/fleakr/objects/image.rb

@@ -24,11 +24,11 @@ module Fleakr
 
       include Fleakr::Support::Object
 
-      flickr_attribute :size,   :attribute => :label
-      flickr_attribute :width,  :attribute => :width
-      flickr_attribute :height, :attribute => :height
-      flickr_attribute :url,    :attribute => :source
-      flickr_attribute :page,   :attribute => :url
+      flickr_attribute :size,   :from => '@label'
+      flickr_attribute :width
+      flickr_attribute :height
+      flickr_attribute :url,    :from => '@source'
+      flickr_attribute :page,   :from => '@url'
 
       find_all :by_photo_id, :call => 'photos.getSizes', :path => 'sizes/size'
 
@@ -41,8 +41,8 @@ module Fleakr
       # directory, the file will be created with the original filename from Flickr.  
       # If the target is a file, it will be saved with the specified name.  In the
       # case that the target file already exists, this method will overwrite it.
-      def save_to(target)
-        destination = File.directory?(target) ? "#{target}/#{self.filename}" : "#{target}"
+      def save_to(target, prefix = nil)
+        destination = File.directory?(target) ? "#{target}/#{prefix}#{self.filename}" : "#{target}"
         File.open(destination, 'w') {|f| f << Net::HTTP.get(URI.parse(self.url)) }
       end
     

data/lib/fleakr/objects/photo.rb

@@ -7,6 +7,10 @@ module Fleakr
     #
     # [id] The ID for this photo
     # [title] The title of this photo
+    # [description] The description of this photo
+    # [secret] This photo's secret (used for sharing photo without permissions checking)
+    # [comment_count] Count of the comments attached to this photo
+    # [url] This photo's page on Flickr
     # [square] The tiny square representation of this photo
     # [thumbnail] The thumbnail for this photo
     # [small] The small representation of this photo
@@ -25,18 +29,78 @@ module Fleakr
 
       include Fleakr::Support::Object
 
-      flickr_attribute :title, :attribute => 'title'
-      flickr_attribute :id, :attribute => 'id'
-      flickr_attribute :farm_id, :attribute => 'farm'
-      flickr_attribute :server_id, :attribute => 'server'
-      flickr_attribute :secret, :attribute => 'secret'
+      flickr_attribute :id, :from => ['@id', 'photoid']
+      flickr_attribute :title
+      flickr_attribute :description
+      flickr_attribute :farm_id, :from => '@farm'
+      flickr_attribute :server_id, :from => '@server'
+      flickr_attribute :secret
+      flickr_attribute :posted
+      flickr_attribute :taken
+      flickr_attribute :updated, :from => '@lastupdate'
+      flickr_attribute :comment_count, :from => 'comments'
+      flickr_attribute :url
+
+      # TODO:
+      # * owner (user)
+      # * visibility
+      # * editability
+      # * usage
+      # * notes
+      # * tags
 
       find_all :by_photoset_id, :call => 'photosets.getPhotos', :path => 'photoset/photo'
       find_all :by_user_id, :call => 'people.getPublicPhotos', :path => 'photos/photo'
       find_all :by_group_id, :call => 'groups.pools.getPhotos', :path => 'photos/photo'
       
+      find_one :by_id, :using => :photo_id, :call => 'photos.getInfo', :authenticate? => true
+      
+      lazily_load :posted, :taken, :updated, :comment_count, :url, :description, :with => :load_info
+      
       has_many :images
 
+      # Upload the photo specified by <tt>filename</tt> to the user's Flickr account.  This
+      # call requires authentication.
+      #
+      def self.upload(filename)
+        response = Fleakr::Api::UploadRequest.with_response!(filename)
+        photo = Photo.new(response.body)
+        Photo.find_by_id(photo.id, :authenticate? => true)
+      end
+
+      # Replace the current photo's image with the one specified by filename.  This 
+      # call requires authentication.
+      #
+      def replace_with(filename)
+        response = Fleakr::Api::UploadRequest.with_response!(filename, :photo_id => self.id, :type => :update)
+        self.populate_from(response.body)
+        self
+      end
+
+      # TODO: Refactor this to remove duplication w/ User#load_info - possibly in the lazily_load class method
+      def load_info # :nodoc:
+        response = Fleakr::Api::MethodRequest.with_response!('photos.getInfo', :photo_id => self.id)
+        self.populate_from(response.body)
+      end
+
+      # When was this photo posted?
+      #
+      def posted_at
+        Time.at(posted.to_i)
+      end
+      
+      # When was this photo taken?
+      #
+      def taken_at
+        Time.parse(taken)
+      end
+      
+      # When was this photo last updated?  This includes addition of tags and other metadata.
+      #
+      def updated_at
+        Time.at(updated.to_i)
+      end
+
       # Create methods to access image sizes by name
       SIZES.each do |size|
         define_method(size) do