fleakr 0.3.0 → 0.4.0

data/README.rdoc

@@ -2,7 +2,7 @@
 
 == Description
 
-A teeny tiny gem to interface with Flickr photostreams
+A small, yet powerful, gem to interface with Flickr photostreams
 
 == Installation
 
@@ -22,16 +22,24 @@ Or ...
 
 == Usage
 
-Before doing anything, require the library:
+To get started, you'll need to grab an API key from Flickr to at least perform any of
+the non-authenticated, read-only calls.  Head on over to the Flickr site to grab one, I'll
+be here when you get back: http://www.flickr.com/services/api/misc.api_keys.html
 
-    >> require 'rubygems'
-    >> require 'fleakr'
+Now that you have your key, you can get things rolling with irb and the fleakr gem:
 
+    $ irb -r rubygems
+    >> require 'fleakr'
+    
 Then, set your API key (only need to do this once per session):
 
     >> Fleakr.api_key = '<your api key here>'
-    
-Find a user by username:
+
+=== A Brief Tour
+
+With just an API key, you have the ability to retrieve a substantial amount of data 
+about users, their photosets, photos, contacts, and groups.  Let's start by finding a 
+user by his username:
 
     >> user = Fleakr.user('the decapitator')
     => #<Fleakr::Objects::User:0x692648 @username="the decapitator", @id="21775151@N06">
@@ -47,13 +55,18 @@ Once you have a user, you can find his associated sets:
     => [#<Fleakr::Objects::Set:0x671358 @title="The Decapitator", @description="">, 
         #<Fleakr::Objects::Set:0x66d898 @title="londonpaper hijack", ...
 
+His individual photos:
+
+    >> user.photos.first
+    => #<Fleakr::Objects::Photo:0x161b024 @title="\"Be Fabulous\"" ... >
+
 Or contacts:
 
     >> user.contacts.first
     => #<Fleakr::Objects::User:0x19039bc @username=".schill",
         @id="12289718@N00", @icon_farm="1", @icon_server="4">
 
-Or groups if you would like:
+Or his groups if you would like:
     
     >> user.groups
     => [#<Fleakr::Objects::Group:0x11f2330 ..., 
@@ -77,20 +90,59 @@ When accessing a set, you can also grab all the photos that are in that set:
     >> user.sets.first.photos.first.title
     => "Untitled1"
     
+=== Photos
+
+Each photo object contains metadata about a collection of images, each representing different
+sizes.  Once we have a single photo:
+    
+    >> photo = user.photos.first
+    => #<Fleakr::Objects::Photo:0x161b024 @title="\"Be Fabulous\"" ... >
+    
+We can get information about one of the sizes:
+
+    >> photo.small
+    => #<Fleakr::Objects::Image:0x1768f1c @height="172", @size="Small", @width="240",
+        @url="http://farm4.static.flickr.com/3250/2924549350_cbc1804258_m.jpg",  
+        @page="http://www.flickr.com/photos/the_decapitator/2924549350/sizes/s/">
+
+Grab the URL for the image itself:
+
+    >> photo.small.url
+    => "http://farm4.static.flickr.com/3250/2924549350_cbc1804258_m.jpg"
+    
+Or grab the URL for its page on the Flickr site:
+    
+    >> photo.small.page
+    => "http://www.flickr.com/photos/the_decapitator/2924549350/sizes/s/"
+    
+Other sizes are available (:square, :thumbnail, :small, :medium, :large, :original) and
+are accessed in the same way:
+    
+    >> photo.original.url
+    => "http://farm4.static.flickr.com/3250/2924549350_1cf67c2d47_o.jpg"    
+
+=== Saving Images
+
 If a photo interests you, save it down to a directory of your choosing:
 
-    >> user.sets.first.photos.first.small.save_to('/tmp')
-    => #<File:/tmp/2117922283_715587b2cb_m.jpg (closed)>
+    >> photo.original.save_to('/tmp')
+    => #<File:/tmp/2924549350_1cf67c2d47_o.jpg (closed)>
     
-If you can't decide on a photo and would rather just save the whole set, specify the target directory 
-and the size of the images you're interested in:
+Similarly, you can save down entire sets.  Just specify the target directory and the size 
+of the images you're interested in:
 
     >> user.sets.first.save_to('/tmp', :square)
     => [#<Fleakr::Objects::Photo:0x1187a1c @secret="715587b2cb" ...
+    
+This creates a subdirectory within the target directory based on the set's name and preserves
+the original order of the photos:
+    
     >> Dir["/tmp/#{user.sets.first.title}/*.jpg"].map
-    => ["/tmp/The Decapitator/2117919621_8b2d601bff_s.jpg", 
-        "/tmp/The Decapitator/2117921045_5fb15eff90_s.jpg", 
-        "/tmp/The Decapitator/2117922283_715587b2cb_s.jpg", ...
+    => ["/tmp/The Decapitator/01_2117922283_715587b2cb_s.jpg", 
+        "/tmp/The Decapitator/02_2125604584_9c09348fd6_s.jpg", 
+        "/tmp/The Decapitator/03_2118696542_8af5763bde_s.jpg", ... ]
+
+=== Searching
 
 If you would prefer to just search photos, you can do that with search text:
 
@@ -116,13 +168,56 @@ Searches can also be scoped to other entities in the system (namely Users and Gr
     >> user.search('serpent')
     => [#<Fleakr::Objects::Photo:0x18a6960 @server_id="41", @id="81370156",
         @farm_id="1", @title="Clear and Serpent Danger", @secret="013091582a">]
-        
-== TODO
 
-* Implement remaining bits of person, photoset, and photo-releated APIs
+=== Authenticated Calls & Uploads
+
+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 
+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:
+
+1. Your application description and notes are up-to-date
+1. The value for 'Authentication Type' is set to 'Mobile Application'
+1. The value for 'Mobile Permissions' is set to either 'write' or 'delete'
+
+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'
+
+  Fleakr.api_key       = 'ABC123'
+  Fleakr.shared_secret = 'sekrit' # Available with your key details on the Flickr site
+  Fleakr.mini_token    = '362-133-214'
+
+  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.
+
+== Roadmap / TODO
+
+=== 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
-* Lazily load attributes for objects that need to be accessed via secondary API call
-        
+
+=== 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
+
 == License
 
 Copyright (c) 2008 Patrick Reagan (reaganpr@gmail.com)

data/Rakefile

@@ -12,7 +12,7 @@ spec = Gem::Specification.new do |s|
   s.has_rdoc         = true
   s.extra_rdoc_files = %w(README.rdoc)
   s.rdoc_options     = %w(--main README.rdoc)
-  s.summary          = "A teeny tiny gem to interface with Flickr photostreams"
+  s.summary          = "A small, yet powerful, gem to interface with Flickr photostreams"
   s.author           = 'Patrick Reagan'
   s.email            = 'reaganpr@gmail.com'
   s.homepage         = 'http://sneaq.net'

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,57 @@
+module Fleakr
+  module Api # :nodoc:
+    
+    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
+      #
+      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.  Exceptions to this are the <tt>:sign?</tt> and 
+      # <tt>:authenticate?</tt> options that determine if the call should be signed or
+      # authenticated.
+      #
+      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:
+        Response.new(Net::HTTP.get(endpoint_uri))
+      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/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,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/api.rb

@@ -0,0 +1,7 @@
+require "fleakr/api/response"
+require "fleakr/api/method_request"
+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/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/core_ext.rb

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

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'