reagent-fleakr 0.4.1 → 0.4.2

data/README.rdoc

@@ -169,7 +169,33 @@ Searches can also be scoped to other entities in the system (namely Users and Gr
     => [#<Fleakr::Objects::Photo:0x18a6960 @server_id="41", @id="81370156",
         @farm_id="1", @title="Clear and Serpent Danger", @secret="013091582a">]
 
-=== Authenticated Calls & Uploads
+=== Uploading Files
+
+Before you can upload files, you need to be able to make authenticated calls to the Flickr 
+API.  Skip to the next section (Authenticated Calls) for details on how to make this work.
+
+Uploading single files is simple:
+
+    >> Fleakr.upload('/path/to/image.jpg')
+    => [#<Fleakr::Objects::Photo:0x217fb54 @updated="1236133594", @server_id="3266", ...>]
+    
+Notice that the newly-uploaded image is returned.  You can further inspect / modify this as
+necessary.  The real magic is in uploading multiple files - the upload method takes a file
+glob:
+
+    >> Fleakr.upload('/path/to/images/*.jpg')
+    => [#<Fleakr::Objects::Photo:0x217faa0 ...>,
+        #<Fleakr::Objects::Photo:0x212fb18 ...>,
+        #<Fleakr::Objects::Photo:0x20e09c8 ...>]
+
+You can also set options on the file(s) that you're uploading:
+
+    >> Fleakr.upload('/path/to/party/images/*.jpg', :viewable_by => :everyone, 
+                                                    :title => 'Party Pics')
+
+The full list of options can be found in the Fleakr::Objects::Photo documentation.
+
+=== Authenticated Calls
 
 While read-only access to the API gets you quite a bit of data, you'll need to generate an
 authentication token if you want access to the more powerful features (like uploading your 
@@ -197,7 +223,9 @@ confirm access to get your mini-token. Now you're ready to make authenticated re
     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.
+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.
 
 === What Went Wrong?
 
@@ -223,20 +251,19 @@ API requests.
 
 === 0.4.x
 
-* Allow passing of parameters to file uploads to allow for access control / naming
 * Implement remaining bits of person and photo-related API calls (read-only)
-* Automatically sign all calls (if we have a secret), authenticate all calls (if we have a token)
 
 === 0.5.x
 
 * Implement asynchronous file upload / replacement w/ ticket checking
-* Provide a better searching interface
+* Provide a better searching interface with ruby-like option syntax
 
 === Future
 
 * Implement save-able search results (e.g. Fleakr.search('ponies').save_to('/path', :medium))
 * Implement deeper associations for core elements (e.g. tags / etc..)
 * Implement write methods for photos & photosets
+* Implement flickr.places.* portion of API 
 
 == License
 

data/Rakefile

@@ -19,7 +19,7 @@ spec = Gem::Specification.new do |s|
   s.files            = %w(README.rdoc Rakefile) + Dir.glob("{lib,test}/**/*")
   
   s.add_dependency('hpricot', '~> 0.6.0')
-  s.add_dependency('activesupport', '~> 2.2.0')
+  s.add_dependency('activesupport', '~> 2.0')
   s.add_dependency('loggable', '~> 0.2.0')
 end
 

data/lib/fleakr/api/method_request.rb

@@ -1,12 +1,17 @@
 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 
-      # #Fleakr::Api::MethodRequest.new for details about the additional parameters
+      # MethodRequest#new for details about the additional parameters
       #
       def self.with_response!(method, additional_parameters = {})
         request = self.new(method, additional_parameters)
@@ -25,9 +30,9 @@ module Fleakr
       # see (#Fleakr.api_key=)
       #
       # The <tt>additional_parameters</tt> is a list of parameters to pass directly to 
-      # the Flickr API call.  Exceptions to this are the <tt>:sign?</tt> and 
-      # <tt>:authenticate?</tt> options that determine if the call should be signed or
-      # authenticated.
+      # 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)

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: 1
+          when :moderate: 2
+          when :restricted: 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: 1
+          when :screenshot: 2
+          when :other: 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_list.rb

@@ -10,8 +10,8 @@ module Fleakr
     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?
+      # [: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:
@@ -22,7 +22,8 @@ module Fleakr
       #   => #<Fleakr::Api::ValueParameter:0x1656da4 @include_in_signature=true, @name="foo", @value="bar">
       #
       def initialize(options = {})
-        @api_options = options.extract!(:sign?, :authenticate?)
+        # TODO: need to find a way to move the unexpected behavior in Fleakr.token elsewhere
+        @api_options = options.extract!(:authenticate?)
         
         @list = Hash.new
 
@@ -41,13 +42,13 @@ module Fleakr
       # Should this parameter list be signed?
       #
       def sign?
-        (@api_options[:sign?] == true || authenticate?) ? true : false
+        !Fleakr.shared_secret.blank?
       end
       
       # Should we send the auth_token with the request?
       #
       def authenticate?
-        (@api_options[:authenticate?] == true) ? true : false
+        @api_options.has_key?(:authenticate?) ? @api_options[:authenticate?] : !Fleakr.token.blank?
       end
       
       # Access an individual parameter by key (symbol or string)
@@ -64,7 +65,7 @@ module Fleakr
       # list - e.g. <tt>foo=bar&blee=baz</tt>
       #
       def to_query
-        list.values.map(&:to_query).join('&')
+        list.values.map {|element| element.to_query }.join('&')
       end
       
       # Generate the form representation of this parameter list including the

data/lib/fleakr/api/upload_request.rb

@@ -19,8 +19,8 @@ module Fleakr
       # 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)
+      def self.with_response!(filename, type = :create, options = {})
+        request = self.new(filename, type, options)
         response = request.send
         
         raise(Fleakr::ApiError, "Code: #{response.error.code} - #{response.error.message}") if response.error?
@@ -28,21 +28,27 @@ module Fleakr
         response
       end
       
-      # Create a new UploadRequest with the specified filename and options:
+      # Create a new UploadRequest with the specified filename, type, and options.  Type
+      # is one of <tt>:create</tt> or <tt>:update</tt> to specify whether we are saving a new
+      # image or replacing an existing one.  
       #
-      # [:type] Valid values are :create and :update and are used when uploading new 
-      #         photos or replacing existing ones
+      # For a list of available options, see the documentation in Fleakr::Objects::Photo
       #
-      def initialize(filename, options = {})
-        type_options = options.extract!(:type)
-        options.merge!(:authenticate? => true)
+      def initialize(filename, type = :create, options = {})
+        @type    = type
+        @options = options
         
-        @type = type_options[:type] || :create
-        
-        @parameters = ParameterList.new(options)
+        @parameters = ParameterList.new(upload_options)
         @parameters << FileParameter.new('photo', filename)
       end
       
+      # A list of upload options for this upload request (see Fleakr::Api::Option)
+      #
+      def upload_options
+        option_list = @options.map {|key, value| Option.for(key, value) }
+        option_list.inject({}) {|hash, option| hash.merge(option.to_hash)}
+      end
+      
       def headers # :nodoc:
         {'Content-Type' => "multipart/form-data; boundary=#{self.parameters.boundary}"}
       end

data/lib/fleakr/api.rb

@@ -1,5 +1,6 @@
 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"

data/lib/fleakr/core_ext/false_class.rb

@@ -0,0 +1,7 @@
+class FalseClass # :nodoc:
+  
+  def to_i
+    0
+  end
+  
+end

data/lib/fleakr/core_ext/true_class.rb

@@ -0,0 +1,7 @@
+class TrueClass # :nodoc:
+  
+  def to_i
+    1
+  end
+  
+end

data/lib/fleakr/core_ext.rb

@@ -1 +1,3 @@
-require 'fleakr/core_ext/hash'
+require 'fleakr/core_ext/hash'
+require 'fleakr/core_ext/false_class'
+require 'fleakr/core_ext/true_class'

data/lib/fleakr/objects/authentication_token.rb

@@ -17,22 +17,39 @@ module Fleakr
       
       flickr_attribute :value, :from => 'auth/token'
       flickr_attribute :permissions, :from => 'auth/perms'
+      flickr_attribute :user_id, :from => 'auth/user@nsid'
+      flickr_attribute :user_name, :from => 'auth/user@username' 
+      flickr_attribute :full_name, :from => 'auth/user@fullname'
       
       # 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)
+      def self.from_mini_token(mini_token)
+        from :mini_token, mini_token
       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)
+      def self.from_auth_token(auth_token)
+        from :auth_token, auth_token
+      end
+      
+      # Retrieve a full authentication token from the supplied frob
+      def self.from_frob(frob)
+        from :frob, frob
+      end
+      
+      def self.from(thing, value) # :nodoc:
+        api_methods = {
+          :mini_token => 'getFullToken',
+          :auth_token => 'checkToken',
+          :frob       => 'getToken'
+        }
+        
+        method = "auth.#{api_methods[thing]}"
+        
+        parameters = {thing => value, :authenticate? => false}
+        response = Fleakr::Api::MethodRequest.with_response!(method, parameters)
         
         self.new(response.body)
       end

data/lib/fleakr/objects/photo.rb

@@ -3,6 +3,9 @@ module Fleakr
     
     # = Photo
     #
+    # Handles both the retrieval of Photo objects from various associations (e.g. User / Set) as 
+    # well as the ability to upload images to the Flickr site.
+    # 
     # == Attributes
     #
     # [id] The ID for this photo
@@ -59,20 +62,32 @@ module Fleakr
       
       has_many :images
 
-      # Upload the photo specified by <tt>filename</tt> to the user's Flickr account.  This
-      # call requires authentication.
+      # Upload the photo specified by <tt>filename</tt> to the user's Flickr account. When uploading,
+      # there are several options available (none are required):
+      #
+      # [:title] The title for this photo. Any string is allowed.
+      # [:description] The description for this photo. Any string is allowed.
+      # [:tags] A collection of tags for this photo. This can be a string or array of strings.
+      # [:viewable_by] Who can view this photo?  Acceptable values are one of <tt>:everyone</tt>,
+      #                <tt>:friends</tt> or <tt>:family</tt>.  This can also take an array of values
+      #                (e.g. <tt>[:friends, :family]</tt>) to make it viewable by friends and family.
+      # [:level] The safety level of this photo.  Acceptable values are one of <tt>:safe</tt>,
+      #          <tt>:moderate</tt>, or <tt>:restricted</tt>.
+      # [:type] The type of image this is.  Acceptable values are one of <tt>:photo</tt>,
+      #         <tt>:screenshot</tt>, or <tt>:other</tt>.
+      # [:hide?] Should this photo be hidden from public searches? Takes a boolean.
       #
-      def self.upload(filename)
-        response = Fleakr::Api::UploadRequest.with_response!(filename)
+      def self.upload(filename, options = {})
+        response = Fleakr::Api::UploadRequest.with_response!(filename, :create, options)
         photo = Photo.new(response.body)
-        Photo.find_by_id(photo.id, :authenticate? => true)
+        Photo.find_by_id(photo.id)
       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)
+        response = Fleakr::Api::UploadRequest.with_response!(filename, :update, :photo_id => self.id)
         self.populate_from(response.body)
         self
       end

data/lib/fleakr/support/object.rb

@@ -33,8 +33,10 @@ module Fleakr
           target_class = options[:class_name].nil? ? self.name : "Fleakr::Objects::#{options[:class_name]}"
         
           class_eval <<-CODE
-            def self.find_all_#{condition}(value)
-              response = Fleakr::Api::MethodRequest.with_response!('#{options[:call]}', :#{attribute} => value)
+            def self.find_all_#{condition}(value, options = {})
+              options.merge!(:#{attribute} => value)
+              
+              response = Fleakr::Api::MethodRequest.with_response!('#{options[:call]}', options)
               (response.body/'rsp/#{options[:path]}').map {|e| #{target_class}.new(e) }
             end
           CODE

data/lib/fleakr/version.rb

@@ -3,7 +3,7 @@ module Fleakr
     
     MAJOR = 0
     MINOR = 4
-    TINY  = 1
+    TINY  = 2
     
     def self.to_s
       [MAJOR, MINOR, TINY].join('.')

data/lib/fleakr.rb

@@ -5,7 +5,15 @@ require 'uri'
 require 'cgi'
 require 'net/http'
 require 'hpricot'
-require 'activesupport'
+
+# Require only what we need from ActiveSupport
+require 'active_support/core_ext/array'
+require 'active_support/core_ext/module'
+require 'active_support/core_ext/blank'
+require 'active_support/core_ext/time'
+require 'active_support/inflector'
+require 'active_support/core_ext/string'
+
 require 'md5'
 require 'loggable'
 
@@ -75,7 +83,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
+  mattr_accessor :api_key, :shared_secret, :mini_token, :auth_token, :frob
 
   # Find a user based on some unique user data.  This method will try to find
   # the user based on username and will fall back to email if that fails.  Example:
@@ -113,8 +121,12 @@ module Fleakr
   #  Fleakr.upload('/path/to/my/mug.jpg')
   #  Fleakr.upload('/User/Pictures/Party/*.jpg')
   #
-  def self.upload(glob)
-    Dir[glob].each {|file| Fleakr::Objects::Photo.upload(file) }
+  # Additionally, options can be supplied as part of the upload that will apply to all files
+  # that are matched by the pattern passed to <tt>glob</tt>.  For a full list, see 
+  # Fleakr::Objects::Photo.
+  #
+  def self.upload(glob, options = {})
+    Dir[glob].map {|file| Fleakr::Objects::Photo.upload(file, options) }
   end
 
   # Get the authentication token needed for authenticated requests.  Will either use
@@ -122,13 +134,29 @@ module Fleakr
   #
   def self.token
     @token ||= begin
-      if !Fleakr.auth_token.nil?
+      if Fleakr.auth_token
         Fleakr::Objects::AuthenticationToken.from_auth_token(Fleakr.auth_token)
-      else
+      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
   end
+  
+  # Reset the cached token whenever setting a new value for the mini_token, auth_token, or frob
+  #
+  [:mini_token, :auth_token, :frob].each do |attribute|
+    class_eval <<-ACCESSOR
+      def self.#{attribute}=(#{attribute})
+        reset_token
+        @@#{attribute} = #{attribute}
+      end
+    ACCESSOR
+  end
 
+  def self.reset_token # :nodoc: #
+    @token = nil
+  end
   
 end

data/test/fixtures/auth.getToken.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="utf-8"?>
+<rsp stat="ok">
+<auth>
+	<token>abc-123</token>
+	<perms>delete</perms>
+	<user nsid="31066442@N69" fullname="Sir Froot Pants" username="frootpantz"></user>
+</auth>
+</rsp>

data/test/unit/fleakr/api/method_request_test.rb

@@ -26,16 +26,6 @@ module Fleakr::Api
           request.parameters[:method].value.should == 'flickr.people.findByUsername'
         end
         
-        it "should know that it needs to sign the request" do
-          ParameterList.expects(:new).with(:sign? => true).returns(stub(:<< => nil))
-          request = MethodRequest.new('people.findByUsername', :sign? => true)
-        end
-        
-        it "should know that it needs to authenticate the request" do
-          ParameterList.expects(:new).with(:authenticate? => true).returns(stub(:<< => nil))
-          request = MethodRequest.new('activity.userPhotos', :authenticate? => true)
-        end
-
         it "should know the endpoint with full parameters" do
           query_parameters = 'foo=bar'