slaskis-fleakr 0.5.0

data/lib/fleakr/api/upload_request.rb

@@ -0,0 +1,75 @@
+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, 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?
+
+        response
+      end
+      
+      # 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.  
+      #
+      # For a list of available options, see the documentation in Fleakr::Objects::Photo
+      #
+      def initialize(filename, type = :create, options = {})
+        @type    = type
+        @options = 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
+
+      def send # :nodoc:
+        response = Net::HTTP.start(endpoint_uri.host, endpoint_uri.port) do |http| 
+          logger.info("Sending upload request to: #{endpoint_uri}")
+          logger.debug("Request data:\n#{self.parameters.to_form}")
+          logger.debug("Request headers:\n#{self.headers.inspect}")
+          
+          http.post(endpoint_uri.path, self.parameters.to_form, self.headers)
+        end
+        logger.debug("Response data:\n#{response.body}")
+        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,3 @@
+require 'fleakr/core_ext/hash'
+require 'fleakr/core_ext/false_class'
+require 'fleakr/core_ext/true_class'

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/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/true_class.rb

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

data/lib/fleakr/objects.rb

@@ -0,0 +1,13 @@
+require 'fleakr/objects/authentication_token'
+require 'fleakr/objects/collection'
+require 'fleakr/objects/contact'
+require 'fleakr/objects/error'
+require 'fleakr/objects/group'
+require 'fleakr/objects/image'
+require 'fleakr/objects/photo_context'
+require 'fleakr/objects/photo'
+require 'fleakr/objects/comment'
+require 'fleakr/objects/tag'
+require 'fleakr/objects/search'
+require 'fleakr/objects/set'
+require 'fleakr/objects/user'

data/lib/fleakr/objects/authentication_token.rb

@@ -0,0 +1,60 @@
+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'
+      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(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(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
+      
+    end
+    
+  end
+end

data/lib/fleakr/objects/comment.rb

@@ -0,0 +1,49 @@
+module Fleakr
+  module Objects # :nodoc:
+
+    # = Comment
+    #
+    # This class represents a comment that can be associated with a single photo or an
+    # entire photoset.
+    #
+    # == Attributes
+    #
+    # [id] The unique identifier for this comment
+    # [url] The direct URL / permalink to reference this comment
+    # [body] The comment itself - also available with <tt>to_s</tt>
+    #
+    class Comment
+      
+      include Fleakr::Support::Object
+      
+      find_all :by_photo_id, :call => 'photos.comments.getList', :path => 'comments/comment'
+      find_all :by_set_id, :using => :photoset_id, :call => 'photosets.comments.getList', :path => 'comments/comment'
+      
+      flickr_attribute :id
+      flickr_attribute :author_id, :from => '@author'
+      flickr_attribute :created, :from => '@datecreate'
+      flickr_attribute :url, :from => '@permalink'
+      flickr_attribute :body, :from => '.'
+
+      # The user who supplied the comment.  See Fleakr::Objects::User for more information
+      #
+      def author
+        @author ||= User.find_by_id(author_id)
+      end
+      
+      # When was this comment created?
+      #
+      def created_at
+        Time.at(created.to_i)
+      end
+      
+      # The contents of the comment - also available as <tt>body</tt>
+      #
+      def to_s
+        body
+      end
+      
+    end
+    
+  end
+end

data/lib/fleakr/objects/contact.rb

@@ -0,0 +1,31 @@
+module Fleakr
+  module Objects # :nodoc:
+    class Contact # :nodoc:
+
+      include Fleakr::Support::Object
+
+      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::MethodRequest.with_response!('contacts.getPublicList', :user_id => user_id)
+        (response.body/'contacts/contact').map {|c| Contact.new(c).to_user }
+      end
+      
+      def to_user
+        user = User.new
+        self.class.attributes.each do |attribute|
+          attribute_name = attribute.name
+          user.send("#{attribute.name}=".to_sym, self.send(attribute.name))
+        end
+
+        user
+      end
+
+    end
+  end
+end

data/lib/fleakr/objects/error.rb

@@ -0,0 +1,22 @@
+module Fleakr
+  module Objects # :nodoc:
+    # = Error
+    #
+    # == Accessors
+    # 
+    # This class is a simple wrapper for the error response that the API returns.  There are
+    # a couple of attributes:
+    #
+    # [code] The error code as described in the documentation
+    # [message] The associated error message
+    #
+    class Error
+
+      include Fleakr::Support::Object
+
+      flickr_attribute :code, :from => 'err@code'
+      flickr_attribute :message, :from => 'err@msg'
+
+    end
+  end
+end

data/lib/fleakr/objects/group.rb

@@ -0,0 +1,36 @@
+module Fleakr
+  module Objects # :nodoc:
+    
+    # = Group
+    # 
+    # == Accessors
+    #
+    # [id] This group's ID
+    # [name] The name of the group
+    #
+    # == Associations
+    #
+    # [photos] The photos that are in this group
+    #
+    class Group
+
+      include Fleakr::Support::Object
+
+      flickr_attribute :id, :from => '@nsid'
+      flickr_attribute :name
+      flickr_attribute :adult_flag, :from => '@eighteenplus'
+
+      find_all :by_user_id, :call => 'people.getPublicGroups', :path => 'groups/group'
+
+      has_many :photos
+      
+      scoped_search
+      
+      # Is this group adult-only? (e.g. only 18+ allowed to view)
+      def adult?
+        (adult_flag == '1')
+      end
+
+    end
+  end
+end

data/lib/fleakr/objects/image.rb

@@ -0,0 +1,50 @@
+module Fleakr
+  module Objects
+    
+    # = Image
+    #
+    # This class wraps the functionality for saving remote images to disk. It's called
+    # by the Fleakr::Objects::Photo class to save an image with a specific size and would 
+    # typically never be called directly.
+    # 
+    # Example:
+    # 
+    #  user = Fleakr.user('brownout')
+    #  user.photos.first.small.save_to('/tmp')
+    #
+    # == Attributes
+    # 
+    # [size] The name of this image's size (e.g. Square, Large, etc...)
+    # [width] The width of this image
+    # [height] The height of this image
+    # [url] The direct URL for this image
+    # [page] The page on Flickr that represents this photo
+    # 
+    class Image
+
+      include Fleakr::Support::Object
+
+      flickr_attribute :width, :height
+      flickr_attribute :size,   :from => '@label'
+      flickr_attribute :url,    :from => '@source'
+      flickr_attribute :page,   :from => '@url'
+
+      find_all :by_photo_id, :call => 'photos.getSizes', :path => 'sizes/size'
+
+      # The filename portion of the image (without the full URL)
+      def filename
+        self.url.match(/([^\/]+)$/)[1]
+      end
+    
+      # Save this image to the specified directory or file. If the target is a
+      # 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, 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
+    
+    end
+  end
+end

data/lib/fleakr/objects/photo.rb

@@ -0,0 +1,147 @@
+module Fleakr
+  module Objects # :nodoc:
+    
+    # = 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
+    # [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
+    # [medium] The medium representation of this photo
+    # [large] The large representation of this photo
+    # [original] The original photo
+    # [previous] The previous photo based on the current context
+    # [next] The next photo based on the current context 
+    #
+    # == Associations
+    #
+    # [images] The underlying images for this photo.
+    # [tags] The tags for this photo.
+    # [comments] The comments associated with this photo
+    #
+    class Photo
+
+      # Available sizes for this photo
+      SIZES = [:square, :thumbnail, :small, :medium, :large, :original]
+
+      include Fleakr::Support::Object
+      extend Forwardable
+
+      def_delegators :context, :next, :previous
+
+      flickr_attribute :id, :from => ['@id', 'photoid']
+      flickr_attribute :title, :description, :secret, :posted, :taken, :url
+      flickr_attribute :farm_id, :from => '@farm'
+      flickr_attribute :server_id, :from => '@server'
+      flickr_attribute :owner_id, :from => ['@owner', 'owner@nsid']
+      flickr_attribute :updated, :from => '@lastupdate'
+      flickr_attribute :comment_count, :from => 'comments'
+
+      # TODO:
+      # * visibility
+      # * editability
+      # * usage
+
+      find_all :by_set_id, :using => :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'
+      
+      lazily_load :posted, :taken, :updated, :comment_count, :url, :description, :with => :load_info
+      
+      has_many :images, :tags, :comments
+
+      # 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, options = {})
+        response = Fleakr::Api::UploadRequest.with_response!(filename, :create, options)
+        photo = Photo.new(response.body)
+        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, :update, :photo_id => self.id)
+        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
+
+      def context # :nodoc:
+        @context ||= begin
+          response = Fleakr::Api::MethodRequest.with_response!('photos.getContext', :photo_id => self.id)
+          PhotoContext.new(response.body)
+        end
+      end
+
+      # The user who uploaded this photo.  See Fleakr::Objects::User for additional information.
+      # 
+      def owner
+        @owner ||= User.find_by_id(owner_id)
+      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
+          images_by_size[size]
+        end
+      end
+
+      private
+      def images_by_size
+        image_sizes = SIZES.inject({}) {|l,o| l.merge(o => nil)}
+        self.images.inject(image_sizes) {|l,o| l.merge!(o.size.downcase.to_sym => o) }
+      end
+
+    end
+  end
+end