fleakr 0.5.2 → 0.6.0

data/README.rdoc

@@ -12,10 +12,6 @@ A small, yet powerful, gem to interface with Flickr photostreams
 
 === Bleeding Edge
 
-    sudo gem install reagent-fleakr --source=http://gems.github.com
-    
-Or ...
-
     $ git clone git://github.com/reagent/fleakr.git
     $ cd fleakr
     $ rake gem && sudo gem install pkg/fleakr-<version>.gem
@@ -306,8 +302,13 @@ While read-only access to the API gets you quite a bit of data, you'll need to g
 authentication token if you want access to the more powerful features (like uploading your 
 own photos).  
 
-Assuming you've already applied for a key, go back and make sure you have the right settings
-to get your auth token.  Click on the 'Edit key details' link and ensure that:
+Depending on how you intend to use the Flickr API, there are 2 methods for performing
+authenticated calls.
+
+=== Single User
+
+You'll need to configure your API key to to use Mobile authentication. If you're viewing your
+list of keys on the Flickr site, click on the 'Edit key details' link and ensure that:
 
 1. Your application description and notes are up-to-date
 1. The value for 'Authentication Type' is set to 'Mobile Application'
@@ -315,22 +316,56 @@ to get your auth token.  Click on the 'Edit key details' link and ensure that:
 
 Once this is set, you'll see your Authentication URL on the key details page (it will look
 something like http://www.flickr.com/auth-534525246245).  Paste this URL into your browser and 
-confirm access to get your mini-token. Now you're ready to make authenticated requests:
-
-    require 'rubygems'
-    require 'fleakr'
+confirm access to get your mini-token. Now you're ready to configure your authentication token:
 
     Fleakr.api_key       = 'ABC123'
     Fleakr.shared_secret = 'sekrit' # Available with your key details on the Flickr site
-    Fleakr.mini_token    = '362-133-214'
-
+    
+    token = Fleakr.token_from_mini_token('294-585-410')
+    Fleakr.auth_token = token.value
+    
     Fleakr.upload('/path/to/my/photo.jpg')
-    Fleakr.token.value # => "34132412341235-12341234ef34"
 
-Once you use the mini-token once, it is no longer available.  To use the generated auth_token
-for future requests, just set Fleakr.auth_token to the generated value.  Similarly, if you have
-an authenticated frob from Flickr (using authentication for desktop applications, for example)
-you can also set <tt>Fleakr.frob</tt> to the frob value returned from the API.
+Once you use the mini-token once it is no longer available.  To use the generated auth_token
+for future requests, you'll need to make sure that you set the value permanently:
+
+    Fleakr.auth_token = '72157622657341094-41241e527f325abb'
+    
+=== Multiple Users
+
+If you need to have your application access other users photos on their behalf, you'll want to
+use the Web authentication method.  Edit your key details and make sure that:
+
+1. Your application description and notes are up-to-date
+1. The value for 'Authentication Type' is set to 'Web Application'
+1. You configure your callback URL to point to something valid and accessible
+
+Make sure that your key and secret are set as above. You can then begin the process by requesting 
+that the user authorize access to his Flickr account by redirecting to an authorization URL.  I'm 
+assuming Rails conventions here, but this should work with any Ruby web framework:
+
+    redirect_to Fleakr.authorization_url
+    
+By default, we request read permission for access.  This doesn't really do much more than what the
+public API allows, so you can request different permissions when asking for authorization:
+
+    # The values :read, :write, and :delete are supported
+    redirect_to Fleakr.authorization_url(:delete)
+
+One the user authorizes your application, he will be redirected back to your callback URL with a 
+<tt>frob</tt> parameter as part of the query string.  You'll need to exchange this for a token:
+
+    token = Fleakr.token_from_frob(params[:frob])
+    
+The actual authentication token is available by calling <tt>token.value</tt> in the above 
+example.  You'll want to store this value somewhere to make future API calls on behalf of this
+user. To make that process easier, there is a method that you can use that will allow you to 
+automatically scope your requests to the authenticated user:
+
+    user = Fleakr.user_for_token('72157622657341094-41241e527f325abb')
+    
+From there, you can make any of the usual calls available with the API. See 
+Fleakr::Objects::User for more information.
 
 === What Went Wrong?
 

data/lib/fleakr.rb

@@ -1,5 +1,4 @@
 $:.unshift(File.dirname(__FILE__))
-require 'rubygems'
 
 require 'uri'
 require 'cgi'
@@ -19,9 +18,9 @@ require 'digest/md5'
 require 'fileutils'
 require 'loggable'
 
+require 'fleakr/support'
 require 'fleakr/api'
 require 'fleakr/core_ext'
-require 'fleakr/support'
 require 'fleakr/objects'
 
 # = Fleakr: A small, yet powerful, gem to interface with Flickr photostreams
@@ -85,7 +84,7 @@ module Fleakr
   # Generic catch-all exception for any API errors
   class ApiError < StandardError; end
 
-  mattr_accessor :api_key, :shared_secret, :mini_token, :auth_token, :frob
+  mattr_accessor :api_key, :shared_secret, :auth_token
 
   # Find a user based on some unique user data.  This method will try to find
   # the user based on several methods, starting with username and falling back to email and URL
@@ -96,11 +95,11 @@ module Fleakr
   #  Fleakr.user('user@host.com')
   #  Fleakr.user('http://www.flickr.com/photos/the_decapitator/')
   #
-  def self.user(user_data)
+  def self.user(user_data, options = {})
     user = nil
     [:username, :email, :url].each do |attribute|
       if user.nil?
-        user = Objects::User.send("find_by_#{attribute}", user_data) rescue nil
+        user = Objects::User.send("find_by_#{attribute}", user_data, options) rescue nil
       end
     end
     user
@@ -156,34 +155,43 @@ module Fleakr
     Fleakr::Objects::Contact.find_all(options)
   end
 
-  # Get the authentication token needed for authenticated requests.  Will either use
-  # a valid auth_token (if available) or a mini-token to generate the auth_token.
-  #
-  def self.token
-    @token ||= begin
-      if Fleakr.auth_token
-        Fleakr::Objects::AuthenticationToken.from_auth_token(Fleakr.auth_token)
-      elsif Fleakr.frob
-        Fleakr::Objects::AuthenticationToken.from_frob(Fleakr.frob)
-      elsif Fleakr.mini_token
-        Fleakr::Objects::AuthenticationToken.from_mini_token(Fleakr.mini_token)
-      end
-    end
+  # Generate an authorization URL to redirect users to.  This defaults to 
+  # 'read' permission, but others are available when passed to this method:
+  #
+  #  * :read - permission to read private information (default)
+  #  * :write - permission to add, edit and delete photo metadata (includes 'read')
+  #  * :delete - permission to delete photos (includes 'write' and 'read')
+  #
+  def self.authorization_url(permissions = :read)
+    request = Fleakr::Api::AuthenticationRequest.new(:perms => permissions)
+    request.authorization_url
+  end
+
+  # Exchange a frob for an authentication token.  See Fleakr.authorization_url for
+  # more information.
+  #
+  def self.token_from_frob(frob)
+    Fleakr::Objects::AuthenticationToken.from_frob(frob)
   end
   
-  # Reset the cached token whenever setting a new value for the mini_token, auth_token, or frob
+  # Exchange a mini token for an authentication token.
   #
-  [:mini_token, :auth_token, :frob].each do |attribute|
-    class_eval <<-ACCESSOR
-      def self.#{attribute}=(#{attribute})
-        reset_token
-        @@#{attribute} = #{attribute}
-      end
-    ACCESSOR
+  def self.token_from_mini_token(mini_token)
+    Fleakr::Objects::AuthenticationToken.from_mini_token(mini_token)
   end
 
-  def self.reset_token # :nodoc: #
-    @token = nil
+  # Get the user that this authentication token belongs to.  Useful for pulling
+  # relationships scoped to this user.
+  #
+  def self.user_for_token(auth_token)
+    token = Fleakr::Objects::AuthenticationToken.from_auth_token(auth_token)
+    token.user
   end
-  
+
+end
+
+# Alias Fleakr methods as Flickr if possible
+if defined?(Flickr).nil?
+  Flickr = Fleakr
 end
+

data/lib/fleakr/api.rb

@@ -1,4 +1,5 @@
 require "fleakr/api/response"
+require "fleakr/api/authentication_request"
 require "fleakr/api/method_request"
 require "fleakr/api/option"
 require "fleakr/api/upload_request"

data/lib/fleakr/api/authentication_request.rb

@@ -0,0 +1,32 @@
+module Fleakr
+  module Api # :nodoc:
+    
+    # = AuthenticationRequest
+    #
+    # Handles authentication requests for the web authentication method.
+    # Requires that Fleakr.api_key and Fleakr.shared_secret both be set.
+    #
+    class AuthenticationRequest
+      
+      include Fleakr::Support::Request
+
+      # The endpoint for the authentication request
+      #
+      def endpoint_url
+        'http://flickr.com/services/auth/'
+      end
+      
+      def response # :nodoc:
+        Net::HTTP.get_response(endpoint_uri)
+      end
+      
+      # The authorization URL that the user should be redirected to.
+      #
+      def authorization_url
+        @authorization_url ||= response.header['Location']
+      end
+      
+    end
+    
+  end
+end

data/lib/fleakr/api/file_parameter.rb

@@ -5,19 +5,21 @@ module Fleakr
     #
     # Parameter class to encapsulate file data sent to the Flickr upload API
     #
-    class FileParameter < Parameter
+    class FileParameter
       
       MIME_TYPES = {
         '.jpg' => 'image/jpeg',
         '.png' => 'image/png',
         '.gif' => 'image/gif'
       }
+
+      attr_reader :name
       
       # Create a parameter with name and specified filename
       #
       def initialize(name, filename)
+        @name     = name
         @filename = filename
-        super(name, false)
       end
       
       # Discover MIME type by file extension using MIME_TYPES constant

data/lib/fleakr/api/method_request.rb

@@ -7,7 +7,10 @@ module Fleakr
     # UploadRequest class.
     #
     class MethodRequest
-      attr_reader :parameters, :method
+      
+      include Fleakr::Support::Request
+      
+      attr_reader :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 
@@ -16,7 +19,7 @@ module Fleakr
       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
@@ -35,14 +38,17 @@ module Fleakr
       # behavior is to authenticate all calls when we have a token).
       #
       def initialize(method, additional_parameters = {})
-        @parameters = ParameterList.new(additional_parameters)
-        
+        super(additional_parameters)
         self.method = method
       end
    
       def method=(method) # :nodoc:
         @method = method.sub(/^(flickr\.)?/, 'flickr.')
-        @parameters << ValueParameter.new('method', @method)
+        parameters.add_option(:method, @method)
+      end
+
+      def endpoint_url
+        'http://api.flickr.com/services/rest/'
       end
 
       def send # :nodoc:
@@ -53,13 +59,6 @@ module Fleakr
         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

data/lib/fleakr/api/parameter_list.rb

@@ -9,89 +9,116 @@ module Fleakr
     #
     class ParameterList
       
+      attr_reader :upload_options # :nodoc:
+      
       # 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(:username => 'reagent')
+      # 
+      # You can also disable the sending of the authentication token using
+      # the second parameter:
       #
-      #   >> 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">
+      #   list = Fleakr::Api::ParameterList.new({}, false)
       #
-      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) }
+      def initialize(options = {}, send_authentication_token = true)
+        @send_authentication_token = send_authentication_token
+        @options                   = options
+        @upload_options            = {}
+      end
 
-        self << ValueParameter.new('api_key', Fleakr.api_key)
-        self << ValueParameter.new('auth_token', Fleakr.token.value) if authenticate?
+      # Should we send an authentication token as part of this list of parameters?
+      # By default this is true if the token is available as a global value or if 
+      # the :auth_token key/value is part of the initial list.  You can override this
+      # in the constructor.
+      # 
+      def send_authentication_token?
+        @send_authentication_token && !authentication_token.nil?
       end
       
-      # Add a new parameter (ValueParameter / FileParameter) to the list
+      # The default options to send as part of the parameter list, defaults to
+      # sending the API key
       #
-      def <<(parameter)
-        @list.merge!(parameter.name => parameter)
+      def default_options
+        {:api_key => Fleakr.api_key}
       end
       
-      # Should this parameter list be signed?
+      # Should this parameter list be signed? This will be true if Fleakr.shared_secret
+      # is set, false if not.
       #
       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('&')
+        list.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 = list.map {|p| "--#{boundary}\r\n#{p.to_form}" }.join
+        form << "--#{boundary}--"
 
         form
       end
       
+      # Retrieve the authentication token from either the list of parameters
+      # or the global value (e.g. Fleakr.auth_token)
+      #
+      def authentication_token
+        Fleakr.auth_token.nil? ? @options[:auth_token] : Fleakr.auth_token
+      end
+      
+      # Add an option to the list that should be sent with a request.
+      #
+      def add_option(name, value)
+        @options.merge!(name => value)
+      end
+      
+      # Add an option that should be sent with an upload request.
+      #
+      def add_upload_option(name, value)
+        @upload_options.merge!(name => value)
+      end
+      
+      def options # :nodoc:
+        options = default_options.merge(@options)
+        options.merge!(:auth_token => authentication_token) if send_authentication_token?
+        
+        options
+      end
+      
+      def boundary # :nodoc:
+        @boundary ||= Digest::MD5.hexdigest(rand.to_s)
+      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
+        sorted_options = options_without_signature.sort {|a,b| a[0].to_s <=> b[0].to_s }
+        signature_text = sorted_options.map {|o| "#{o[0]}#{o[1]}" }.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
+      def options_without_signature # :nodoc:
+        options.reject {|k,v| k.to_s == 'api_sig'}
+      end
+      
+      def options_with_signature # :nodoc:
+        options_without_signature.merge(:api_sig => signature)
       end
+      
+      def list # :nodoc:
+        options_for_list = sign? ? options_with_signature : options_without_signature 
+        value_parameters = options_for_list.map {|k,v| ValueParameter.new(k, v) }
+        file_parameters  = upload_options.map {|k,v| FileParameter.new(k, v) }
+
+        value_parameters + file_parameters
+      end
+
     end
   end
 end