rscribd 0.0.2 → 0.0.3

data/History.txt

@@ -0,0 +1,3 @@
+=== 0.0.3 / 2008-02-18
+
+* Initial RubyForge project

data/Manifest.txt

@@ -0,0 +1,14 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+lib/api.rb
+lib/doc.rb
+lib/exceptions.rb
+lib/multipart.rb
+lib/resource.rb
+lib/rscribd.rb
+lib/user.rb
+sample/01_upload.rb
+sample/02_user.rb
+sample/test.txt

data/README.txt

@@ -0,0 +1,83 @@
+= rscribd
+
+* 1.0.3 (Jan 3, 2007)
+
+== DESCRIPTION:
+
+This gem provides a simple and powerful library for the Scribd API, allowing you
+to write Ruby applications or Ruby on Rails websites that upload, convert,
+display, search, and control documents in many formats.
+
+== FEATURES/PROBLEMS:
+
+* Upload your documents to Scribd's servers and access them using the gem
+* Upload local files or from remote web sites
+* Search, tag, and organize documents
+* Associate documents with your users' accounts
+
+== SYNOPSIS:
+
+This API allows you to use Scribd's Flash viewer on your website. You'll be able
+to take advantage of Scribd's scalable document conversion system to convert
+your documents into platform-independent formats. You can leverage Scribd's
+storage system to store your documents in accessible manner. Scribd's ad system
+will help you monetize your documents easily.
+
+First, you'll need to get a Scribd API account. Visit
+http://www.scribd.com/platform to apply for a platform account.
+
+On the Platform site you will be given an API key and secret. The API object
+will need these to authenticate you:
+
+  require 'rscribd'
+  Scribd::API.instance.key = 'your API key'
+  Scribd::API.instance.secret = 'your API secret'
+
+Next, log into the Scribd website:
+
+  Scribd::User.login 'username', 'password'
+
+You are now ready to use Scribd to manage your documents. For instance, to
+upload a document:
+
+  doc = Scribd::Document.upload(:file => 'your-file.pdf')
+
+For more information, please see the documentation for the Scribd::API,
+Scribd::User, and Scribd::Document classes. (You can also check out the docs for
+the other classes for a more in-depth look at this gem's features).
+
+== REQUIREMENTS:
+
+* A Scribd API account
+* mime-types gem
+
+== INSTALL:
+
+* The client library is a RubyGem called *rscribd*. To install, type:
+
+  sudo gem install rscribd
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2007-2008 The Scribd Team
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,18 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+
+Hoe.new('rscribd', '0.0.3') do |p|
+  p.rubyforge_name = 'rscribd'
+  p.author = 'Jared Friedman'
+  p.email = 'api@scribd.com'
+  p.summary = 'Ruby client library for the Scribd API'
+  p.description = p.paragraphs_of('README.txt', 2..5).join("\n\n")
+  p.url = p.paragraphs_of('README.txt', 0).first.split(/\n/)[1..-1]
+  p.changes = p.paragraphs_of('History.txt', 0..1).join("\n\n")
+  p.extra_deps << [ 'mime-types', '>0.0.0' ]
+  p.remote_rdoc_dir = ''
+end
+
+# vim: syntax=Ruby

data/lib/api.rb

@@ -0,0 +1,219 @@
+require 'singleton'
+require 'md5'
+require 'rexml/document'
+
+module Scribd
+  
+  # This class acts as the top-level interface between Scribd and your
+  # application. Before you can begin using the Scribd API, you must specify for
+  # this object your API key and API secret. They are available on your
+  # Platform home page.
+  #
+  # This class is a singleton. Its only instance is accessed using the
+  # +instance+ class method.
+  #
+  # To begin, first specify your API key and secret:
+  #
+  #  Scribd::API.instance.key = 'your API key here'
+  #  Scribd::API.instance.secret = 'your API secret here'
+  #
+  # (If you set the +SCRIBD_API_KEY+ and +SCRIBD_API_SECRET+ Ruby environment
+  # variables before loading the gem, these values will be set automatically for
+  # you.)
+  #
+  # Next, you should log in to Scribd, or create a new account through the gem.
+  #
+  #  user = Scribd::User.login 'login', 'password'
+  #
+  # You are now free to use the Scribd::User or Scribd::Document classes to work
+  # with Scribd documents or your user account.
+  #
+  # If you need the Scribd::User instance for the currently logged in user at a
+  # later point in time, you can retrieve it using the +user+ attribute:
+  #
+  #  user = Scribd::API.instance.user
+  #
+  # In addition, you can save and restore sessions by simply storing this user
+  # instance and assigning it to the API at a later time. For example, to
+  # restore the session retrieved in the previous example:
+  #
+  #  Scribd::API.instance.user = user
+  #
+  # In addition to working with Scribd users, you can also work with your own
+  # website's user accounts. To do this, set the Scribd API user to a string
+  # containing a unique identifier for that user (perhaps a login name or a user
+  # ID):
+  #
+  #  Scribd::API.instance.user = my_user_object.mangled_user_id
+  #
+  # A "phantom" Scribd user will be set up with that ID, so you any documents
+  # you upload will be associated with that account.
+  #
+  # For more hints on what you can do with the Scribd API, please see the
+  # Scribd::Document class.
+  
+  class API
+    include Singleton
+    
+    HOST = 'api.scribd.com' #:nodoc:
+    PORT = 80 #:nodoc:
+    REQUEST_PATH = '/api' #:nodoc:
+    TRIES = 3 #:nodoc:
+    
+    attr_accessor :key # The API key you were given when you created a Platform account.
+    attr_accessor :secret # The API secret used to validate your key (also provided with your account).
+    attr_accessor :user # The currently logged in user.
+    attr_accessor :asynchronous # If true, requests are processed asynchronously. If false, requests are blocking.
+    attr_accessor :debug # If true, extended debugging information is printed
+    
+    def initialize #:nodoc:
+      @asychronous = false
+      @key = ENV['SCRIBD_API_KEY']
+      @secret = ENV['SCRIBD_API_SECRET']
+    end
+    
+    def send_request(method, fields={}) #:nodoc:
+      raise NotReadyError unless @key and @secret
+      # See if method is given
+      raise ArgumentError, "Method should be given" if method.nil? || method.empty?
+      
+      debug("** Remote method call: #{method}; fields: #{fields.inspect}")
+      
+      # replace pesky hashes to prevent accidents
+      fields = fields.stringify_keys
+
+      # Complete fields with the method name
+      fields['method'] = method
+      fields['api_key'] = @key
+      
+      if fields['session_key'].nil? and fields['my_user_id'].nil? then
+        if @user.kind_of? Scribd::User then
+          fields['session_key'] = @user.session_key
+        elsif @user.kind_of? String then
+          fields['my_user_id'] = @user
+        end
+      end
+      
+      nil_fields = fields.keys.select { |key| fields[key] == nil }
+      nil_fields.each { |key| fields.delete key }
+
+      # Don't include file in parameters to calculate signature
+      sign_fields = {} 
+      fields.map {|k,v| sign_fields[k] = v if k != 'file' }
+      #fields.delete_if {|k,v| k=='file'} 
+
+      fields['api_sig'] = sign(sign_fields)
+      debug("** POST parameters: #{fields.inspect}")
+
+      # Create the connection
+      http = Net::HTTP.new(HOST, PORT)
+      # TODO configure timeouts through the properties
+
+      # API methods can be SLOW.  Make sure this is set to something big to prevent spurious timeouts
+      http.read_timeout = 15*60
+
+      request = Net::HTTP::Post.new(REQUEST_PATH)
+      request.multipart_params = fields
+
+      tries = TRIES
+      begin
+        tries -= 1
+        res = http.request(request)
+      rescue Exception
+        $stderr.puts "Request encountered error, will retry #{tries} more."
+        if tries > 0
+          # Retrying several times with sleeps is recommended.
+          # This will prevent temporary downtimes at Scribd from breaking API applications
+          sleep(20)
+          retry
+        end
+        raise $!
+      end
+      
+      debug "** Response:"
+      debug(res.body)
+      debug "** End response"
+
+      # Convert response into XML
+      xml = REXML::Document.new(res.body)
+      raise MalformedResponseError, "The response received from the remote host could not be interpreted" unless xml.elements['/rsp']
+
+      # See if there was an error and raise an exception
+      if xml.elements['/rsp'].attributes['stat'] == 'fail'
+        # Load default code and error
+        code, message = -1, "Unidentified error:\n#{res.body}"
+
+        # Get actual error code and message
+        err = xml.elements['/rsp/error']
+        code, message = err.attributes['code'], err.attributes['message'] if err
+
+        # Add more data
+        message = "Method: #{method} Response: code=#{code} message=#{message}"
+
+        raise ResponseError.new(code), message
+      end
+
+      return xml
+    end
+
+    private 
+
+    # FIXME: Since we don't need XMLRPC, the exception could be different
+    # TODO: It would probably be better if we wrapped the fault
+    # in something more meaningful. At the very least, a broad
+    # division of errors, such as retryable and fatal. 
+    def error(el) #:nodoc:
+      att = el.attributes
+      fe = XMLRPC::FaultException.new(att['code'].to_i, att['msg'])
+      $stderr.puts "ERR: #{fe.faultString} (#{fe.faultCode})"
+      raise fe
+    end
+
+    # Checks if a string parameter is given and not empty.
+    # 
+    # Parameters:
+    #   name  - parameter name for an error message.
+    #   value - value.
+    #   
+    # Raises:
+    #   ArgumentError if the value is nil, or empty.
+    #
+    def check_not_empty(name, value) #:nodoc:
+      check_given(name, value)
+      raise ArgumentError, "#{name} must not be empty" if value.to_s.empty?
+    end
+
+    # Checks if the value is given.
+    #
+    # Parameters:
+    #   name  - parameter name for an error message.
+    #   value - value.
+    #   
+    # Raises:
+    #   ArgumentError if the value is nil.
+    #
+    def check_given(name, value) #:nodoc:
+      raise ArgumentError, "#{name} must be given" if value.nil?
+    end
+    
+    # Sign the arguments hash with our very own signature.
+    #
+    # Parameters:
+    #   args - method arguments to be sent to the server API
+    # 
+    # Returns:
+    #   signature
+    #
+    def sign(args)
+      return MD5.md5(@secret + args.sort.flatten.join).to_s
+    end
+    
+    # Outputs whatever is given into the $stderr if debugging is enabled.
+    #
+    # Parameters:
+    #   args - content to output
+    def debug(*args)
+      $stderr.puts(sprintf(*args)) if @debug
+    end
+  end
+end

data/lib/doc.rb

@@ -0,0 +1,233 @@
+require "uri"
+
+module Scribd
+  
+  # A document as shown on the Scribd website. API programs can upload documents
+  # from files or URL's, tag them, and change their settings. An API program can
+  # access any document, but it can only modify documents owned by the logged-in
+  # user.
+  #
+  # To upload a new document to Scribd, you must create a new Document instance,
+  # set the +file+ attribute to the file's path, and then save the document:
+  #
+  #  doc = Scribd::Document.new
+  #  doc.file = '/path/or/URL/of/file.txt'
+  #  doc.save
+  #
+  # You can do this more simply with one line of code:
+  #
+  #  doc = Scribd::Document.create :file => '/path/or/URL/of/file.txt'
+  #
+  # If you are uploading a file that does not have an extension (like ".txt"),
+  # you need to specify the +type+ attribute as well:
+  #
+  #  doc = Scribd::Document.upload :file => 'CHANGELOG', :type => 'txt'
+  #
+  # Aside from these two attributes, you can set other attributes that affect
+  # how the file is displayed on Scribd. See the API documentation online for a
+  # list of attributes, at http://www.scribd.com/platform/documentation?method_name=docs.search&subtab=api
+  # (consult the "Result explanation" section).
+  #
+  # These attributes can be accessed or changed directly
+  # (<tt>doc.title = 'Title'</tt>). You must save a document after changing its
+  # attributes in order for those changes to take effect. Not all attributes can
+  # be modified; see the API documentation online for details.
+  #
+  # A document can be associated with a Scribd::User via the +owner+ attribute.
+  # This is not always the case, however. Documents retrieved from the find
+  # method will not be associated with their owners.
+  #
+  # The +owner+ attribute is read/write, however, changes made to it only apply
+  # _before_ the document is saved. Once it is saved, the owner is set in stone
+  # and cannot be modified:
+  #
+  #  doc = Scribd::Document.new :file => 'test.txt'
+  #  doc.user = Scribd::User.signup(:username => 'newuser', :password => 'newpass', :email => 'your@email.com')
+  #  doc.save #=> Uploads the document as "newuser", regardless of who the Scribd API user is
+  #  doc.user = Scribd::API.instance.user #=> raises NotImplementedError 
+  
+  class Document < Resource
+    
+    # Creates a new, unsaved document with the given attributes. The document
+    # must be saved before it will appear on the website.
+    
+    def initialize(options={})
+      super
+      if options[:xml] then
+        load_attributes(options[:xml])
+        @attributes[:owner] = options[:owner]
+        @saved = true
+        @created = true
+      else
+        @attributes = options
+      end
+    end
+    
+    # For document objects that have not been saved for the first time, uploads
+    # the document, sets its attributes, and saves it. Otherwise, updates any
+    # changed attributes and saves it. Returns true if the save completed
+    # successfully. Throws an exception if save fails.
+    #
+    # For first-time saves, you must have specified a +file+ attribute. This can
+    # either be a local path to a file, or an HTTP, HTTPS, or FTP URL. In either
+    # case, the file at that location will be uploaded to create the document.
+    #
+    # If you create a document, specify the +file+ attribute again, and then
+    # save it, Scribd replaces the existing document with the file given, while
+    # keeping all other properties (title, description, etc.) the same, in a
+    # process called _revisioning_.
+    #
+    # This method can throw a +Timeout+ exception if the connection is slow or
+    # inaccessible. A ResponseError will be thrown if a remote problem occurs.
+    # A PrivilegeError will be thrown if you try to upload a new revision for a
+    # document with no associated user (i.e., one retrieved from the find
+    # method).
+    #
+    # You must specify the +type+ attribute alongside the +file+ attribute if
+    # the file's type cannot be determined from its name.
+    
+    def save
+      if not created? and @attributes[:file].nil? then
+        raise "'file' attribute must be specified for new documents"
+        return false
+      end
+      
+      if created? and @attributes[:file] and (@attributes[:owner].nil? or @attributes[:owner].session_key.nil?) then
+        raise PrivilegeError, "The current API user is not the owner of this document"
+      end
+      
+      # Make a request form
+      fields = Hash.new
+      if @attributes[:file] then
+        ext = @attributes[:file].split('.').last unless @attributes[:file].index('.').nil?
+        fields[:doc_type] = @attributes[:type]
+        fields[:doc_type] ||= ext
+        fields[:rev_id] = @attributes[:doc_id]
+      end
+      fields[:session_key] = @attributes[:owner].session_key if @attributes[:owner]
+      response = nil
+      
+      if @attributes[:file] then
+        uri = nil
+        begin
+          uri = URI.parse @attributes[:file]
+        rescue URI::InvalidURIError
+          uri = nil # Some valid file paths are not valid URI's (but some are)
+        end
+        if uri.kind_of? URI::HTTP or uri.kind_of? URI::HTTPS or uri.kind_of? URI::FTP then
+          fields[:url] = @attributes[:file]
+          response = API.instance.send_request 'docs.uploadFromUrl', fields
+        elsif uri.kind_of? URI::Generic or uri.nil? then
+          File.open(@attributes[:file]) do |file|
+            fields[:file] = file
+            response = API.instance.send_request 'docs.upload', fields
+          end
+        end
+      end
+      
+      fields = @attributes.dup # fields is what we send to the server
+
+      if response then
+        # Extract our response
+        xml = response.get_elements('/rsp')[0]
+        load_attributes(xml)
+        @created = true
+      end
+      
+      fields.delete :file
+      fields.delete :type
+      
+      changed_attributes = fields.dup # changed_attributes is what we will stick into @attributes once we update remotely
+      
+      fields[:session_key] = fields[:owner].session_key if fields[:owner]
+      changed_attributes[:owner] ||= API.instance.user
+      fields[:doc_ids] = self.id
+      
+      API.instance.send_request('docs.changeSettings', fields)
+      
+      @attributes.update(changed_attributes)
+      
+      @saved = true
+      return true
+    end
+    
+    # Quickly updates an array of documents with the given attributes. The
+    # documents can have different owners, but all of them must be modifiable.
+    
+    def self.update_all(docs, options)
+      raise ArgumentError, "docs must be an array" unless docs.kind_of? Array
+      raise ArgumentError, "docs must consist of Scribd::Document objects" unless docs.all? { |doc| doc.kind_of? Document }
+      raise ArgumentError, "You can't modify one or more documents" if docs.any? { |doc| doc.owner.nil? }
+      raise ArgumentError, "options must be a hash" unless options.kind_of? Hash
+      
+      docs_by_user = docs.inject(Hash.new { |hash, key| hash[key] = Array.new }) { |hash, doc| hash[doc.owner] << doc; hash }
+      docs_by_user.each { |user, doc_list| API.instance.send_request 'docs.changeSettings', options.merge(:doc_ids => doc_list.collect { |doc| doc.id }.join(','), :session_key => user.session_key) }
+    end
+    
+    # Searches for documents matching a query. This method is called with a hash
+    # of options to documents by their content. You must at a minimum supply a
+    # +query+ option, with a string that will become the full-text search query.
+    # For a list of other supported options, please see the online API
+    # documentation at http://www.scribd.com/platform/documentation?method_name=docs.search&subtab=api
+    #
+    # Documents returned from this method will have their +owner+ attributes set
+    # to nil.
+    
+    def self.find(options)
+      raise ArgumentError, "The find method takes a hash of options" unless options.kind_of? Hash
+      raise ArgumentError, "You must specify the query option" unless options[:query]
+      
+      options[:scope] ||= 'all'
+      
+      response = API.instance.send_request('docs.search', options)
+      documents = []
+      response.elements['/rsp/result_set'].elements.each do |doc|
+        documents << Document.new(:xml => doc)
+      end
+      return documents
+    end
+    
+    # Synonym for create.
+    
+    def self.upload(options={})
+      create options
+    end
+    
+    # Returns the conversion status of this document. When a document is
+    # uploaded it must be converted before it can be used. The conversion is
+    # non-blocking; you can query this method to determine whether the document
+    # is ready to be displayed.
+    #
+    # The conversion status is returned as a string. For a full list of
+    # conversion statuses, see the online API documentation at
+    # http://www.scribd.com/platform/documentation?method_name=docs.getConversionStatus&subtab=api
+    #
+    # Unlike other properties of a document, this is retrieved from the server
+    # every time it's queried.
+    
+    def conversion_status
+      response = API.instance.send_request('docs.getConversionStatus', :doc_id => self.id)
+      response.elements['/rsp/conversion_status'].text
+    end
+    
+    # Deletes a document. Returns true if successful.
+    
+    def destroy
+      response = API.instance.send_request('docs.delete', :doc_id => self.id)
+      return response.elements['/rsp'].attributes['stat'] == 'ok'
+    end
+    
+    # Returns the +doc_id+ attribute.
+    
+    def id
+      self.doc_id
+    end
+    
+    # Ensures that the +owner+ attribute cannot be set once the document is
+    # saved.
+    
+    def owner=(newuser) #:nodoc:
+      saved? ? raise(NotImplementedError, "Cannot change a document's owner once the document has been saved") : super
+    end
+  end
+end

data/lib/exceptions.rb

@@ -0,0 +1,33 @@
+module Scribd
+  
+  # Raised when API calls are made before a key and secret are specified.
+  
+  class NotReadyError < StandardError; end
+    
+  # Raised when the XML returned by Scribd is malformed.
+  
+  class MalformedResponseError < StandardError; end
+  
+  # Raised when trying to perform an action that isn't allowed for the current
+  # active user. Note that this exception is thrown only if the error originates
+  # locally. If the request must go out to the Scribd server before the
+  # privilege error occurs, a ResponseError will be thrown. Unless a method's
+  # documentation indicates otherwise, assume that the error will originate
+  # remotely and a ResponseError will be thrown.
+  
+  class PrivilegeError < StandardError; end
+  
+  # Raised when a remote error occurs. Remote errors are referenced by numerical
+  # code. The online API documentation has a list of possible error codes and
+  # their descriptions for each API method.
+  
+  class ResponseError < RuntimeError
+    attr_reader :code # The error code.
+    
+    # Initializes the error with a given code.
+    
+    def initialize(code)
+      @code = code
+    end
+  end
+end

data/lib/multipart.rb

@@ -0,0 +1,39 @@
+require 'net/https'
+require "rubygems"
+require "mime/types" # Requires gem install mime-types
+require "base64"
+require 'cgi'
+
+# This is based on a great snippet from Pivot Labs, used with permission:
+# http://pivots.pivotallabs.com/users/damon/blog/articles/227-standup-04-27-07-testing-file-uploads
+module Net #:nodoc:
+  class HTTP::Post
+    def multipart_params=(param_hash={})
+      boundary_token = [Array.new(8) {rand(256)}].join
+      self.content_type = "multipart/form-data; boundary=#{boundary_token}"
+      boundary_marker = "--#{boundary_token}\r\n"
+      self.body = param_hash.map { |param_name, param_value|
+        boundary_marker + case param_value
+        when File
+          file_to_multipart(param_name, param_value)
+        else
+          text_to_multipart(param_name, param_value.to_s)
+        end
+      }.join('') + "--#{boundary_token}--\r\n"
+    end
+
+    protected
+    def file_to_multipart(key,file)
+      filename = File.basename(file.path)
+      mime_types = MIME::Types.of(filename)
+      mime_type = mime_types.empty? ? "application/octet-stream" : mime_types.first.content_type
+      part = %Q|Content-Disposition: form-data; name="#{key}"; filename="#{filename}"\r\n|
+      part += "Content-Transfer-Encoding: binary\r\n"
+      part += "Content-Type: #{mime_type}\r\n\r\n#{file.read}\r\n"
+    end
+
+    def text_to_multipart(key,value)
+      "Content-Disposition: form-data; name=\"#{key}\"\r\n\r\n#{value}\r\n"
+    end
+  end
+end