scribd-rscribd 1.0.2

data/History.txt

@@ -0,0 +1,56 @@
+=== 1.0.2 / 2009-7-9
+
+* Added support for getting information about the API user when no other user
+  has been logged in.
+* Files to upload can now be specified as both file paths and File streams.
+
+=== 1.0.1 / 2009-3-4
+
+* Fixed a bug that would cause some API parameters to not be sent when uploading
+  a document.
+
+=== 1.0.0 / 2008-11-26
+
+* First release version.
+* Comprehensive RSpec of all code.
+* read_attributes method now works correctly.
+* Uploading a document as a not-yet-created user no longer uploads it into the
+  default API account.
+* Finding documents owned by a not-yet-created user now returns nil.
+* Symbol#to_proc definedd for RScribd use in non-Rails projects.
+* Minor code style improvements.
+
+=== 0.1.2 / 2008-11-26
+
+* Happy Thanksgiving!
+* Potential security issue resolved by having the document's privacy setting set
+  in the same request as the upload.
+* Bug fixed where some files with uppercase extensions would not convert.
+
+=== 0.1.1 / 2008-10-6
+
+* Fixed bug that occurs when parsing empty elements.
+
+=== 0.1.0 / 2008-10-1
+
+* Changed Scribd::Document.find method to take an ActiveRecord-style scope
+  variable (which can be :all, :first, etc.) as its first parameter. Options are
+  now specified as the second parameter.
+* Scribd::Document.find can also be used with a single integer to find a
+  document by ID.
+* Scribd::Document.find now takes offset and limit parameters (for scopes that
+  return arrays of documents).
+* Added a Scribd::Document#download_url method.
+* Should no longer raise an exception when logging in.
+
+=== 0.0.5 / 2008-09-25
+
+* Updated RScribd to work with server-side API changes.
+
+=== 0.0.4 / 2008-02-20
+
+* Fixed a bug that caused errors when Rails models shared the same name as Scribd objects.
+
+=== 0.0.3 / 2008-02-18
+
+* Initial RubyForge project

data/Manifest.txt

@@ -0,0 +1,14 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+lib/scribdapi.rb
+lib/scribddoc.rb
+lib/scribderrors.rb
+lib/scribdmultiparthack.rb
+lib/scribdresource.rb
+lib/rscribd.rb
+lib/scribduser.rb
+sample/01_upload.rb
+sample/02_user.rb
+sample/test.txt

data/README.txt

@@ -0,0 +1,84 @@
+= rscribd
+
+* 1.0.2 (July 9, 2009)
+
+== 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. For more information on
+the Scribd platform, visit http://www.scribd.com/publisher
+
+== FEATURES:
+
+* 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/publisher/api 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,29 @@
+require 'rubygems'
+require 'hoe'
+require 'spec/rake/spectask'
+
+Hoe.spec('rscribd') do |p|
+  p.version = '1.0.2'
+  p.rubyforge_name = 'rscribd'
+  p.author = 'Jared Friedman, Tim Morgan'
+  p.email = 'api@scribd.com'
+  p.summary = 'Ruby client library for the Scribd API'
+  p.description = p.paragraphs_of('README.txt', 3).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
+
+# desc "Verify gem specs"
+# Spec::Rake::SpecTask.new do |t|
+#   t.spec_files = FileList['spec/*.rb']
+#   t.spec_opts = [ '-cfs' ]
+# end
+
+namespace :github do
+  desc "Prepare for GitHub gem packaging"
+  task :prepare do
+    `rake debug_gem > rscribd.gemspec`
+  end
+end

data/lib/rscribd.rb

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+
+module Scribd # :nodoc:
+end
+
+class Symbol
+  def to_proc
+    Proc.new { |*args| args.shift.__send__(self, *args) }
+  end unless method_defined?(:to_proc)
+end
+
+class Hash #:nodoc:
+   # Taken from Rails, with appreciation to DHH
+   def stringify_keys
+     inject({}) do |options, (key, value)|
+       options[key.to_s] = value
+       options
+     end
+   end unless method_defined?(:stringify_keys)
+end
+
+class Array #:nodoc:
+  def to_hsh
+    h = Hash.new
+    each { |k, v| h[k] = v }
+    h
+  end
+end
+
+# The reason these files have such terrible names is so they don't conflict with
+# files in Rails's app/models directory; Rails seems to prefer loading those
+# when require is called.
+require 'scribdmultiparthack'
+require 'scribderrors'
+require 'scribdapi'
+require 'scribdresource'
+require 'scribddoc'
+require 'scribduser'

data/lib/scribdapi.rb

@@ -0,0 +1,218 @@
+require 'singleton'
+require 'digest/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']
+      @user = User.new
+    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
+      
+      fields.reject! { |k, v| v.nil? }
+
+      # Don't include file in parameters to calculate signature
+      sign_fields = fields.dup
+      sign_fields.delete '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 Digest::MD5.hexdigest(@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(str)
+      $stderr.puts(str) if @debug
+    end
+  end
+end

data/lib/scribddoc.rb

@@ -0,0 +1,282 @@
+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/publisher/api?method_name=docs.search (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
+      @download_urls = Hash.new
+      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 Scribd::ResponseError will be thrown if a remote problem
+    # occurs. A Scribd::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 = @attributes.dup
+      if file = @attributes[:file] then
+        fields.delete :file
+        is_file_object = file.is_a?(File)
+        file_path = is_file_object ? file.path : file
+        ext = File.extname(file_path).gsub(/^\./, '')
+        ext = nil if ext == ''
+        fields[:doc_type] = fields.delete(:type)
+        fields[:doc_type] ||= ext
+        fields[:doc_type].downcase! if fields[:doc_type]
+        fields[:rev_id] = fields.delete(:doc_id)
+      end
+      fields[:session_key] = fields.delete(:owner).session_key if fields[: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_obj = is_file_object ? file : File.open(file, 'r')
+          fields[:file] = file_obj
+          response = API.instance.send_request 'docs.upload', fields
+          file_obj.close unless is_file_object
+        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
+      fields.delete :access
+      
+      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(&:id).join(','), :session_key => user.session_key) }
+    end
+    
+    # === Finding by query
+    #
+    # This method is called with a scope and 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/publisher/api?method_name=docs.search
+    #
+    # The scope can be any value given for the +scope+ parameter in the above
+    # website, or <tt>:first</tt> to return the first result only (not an array
+    # of results).
+    #
+    # The +num_results+ option has been aliased as +limit+, and the +num_start+
+    # option has been aliased as +offset+.
+    #
+    # Documents returned from this method will have their +owner+ attributes set
+    # to nil.
+    #
+    #  Scribd::Document.find(:all, :query => 'cats and dogs', :limit => 10)
+    #
+    # === Finding by ID
+    #
+    # Passing in simply a numerical ID loads the document with that ID. You can
+    # pass additional options as defined at
+    # httphttp://www.scribd.com/publisher/api?method_name=docs.getSettings
+    #
+    #  Scribd::Document.find(108196)
+    #
+    # For now only documents that belong to the current user can be accessed in
+    # this manner.
+    
+    def self.find(scope, options={})
+      doc_id = scope if scope.kind_of?(Integer)
+      raise ArgumentError, "You must specify a query or document ID" unless options[:query] or doc_id
+      
+      if doc_id then
+        options[:doc_id] = doc_id
+        response = API.instance.send_request('docs.getSettings', options)
+        return Document.new(:xml => response.elements['/rsp'])
+      else
+        options[:scope] = scope == :first ? 'all' : scope.to_s
+        options[:num_results] = options[:limit]
+        options[:num_start] = options[:offset]
+        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 scope == :first ? documents.first : documents
+      end
+    end
+    
+    class << self
+      alias_method :upload, :create
+    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/publisher/api?method_name=docs.getConversionStatus
+    #
+    # 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
+    
+    # Retrieves a document's download URL. You can provide a format for the
+    # download. Valid formats are listed at
+    # http://www.scribd.com/publisher/api?method_name=docs.getDownloadUrl
+    #
+    # If you do not provide a format, the link will be for the document's
+    # original format.
+    
+    def download_url(format='original')
+      @download_urls[format] ||= begin
+        response = API.instance.send_request('docs.getDownloadUrl', :doc_id => self.id, :doc_type => format)
+        response.elements['/rsp/download_link'].cdatas.first.to_s
+      end
+    end
+  end
+end

data/lib/scribderrors.rb

@@ -0,0 +1,34 @@
+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 Scribd::ResponseError will be thrown. Unless a
+  # method's documentation indicates otherwise, assume that the error will
+  # originate remotely and a Scribd::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
+    # The error code.
+    attr_reader :code
+    
+    # Initializes the error with a given code.
+    
+    def initialize(code)
+      @code = code
+    end
+  end
+end

data/lib/scribdmultiparthack.rb

@@ -0,0 +1,39 @@
+# 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
+
+require 'net/https'
+require 'rubygems'
+require 'mime/types' # Requires gem install mime-types
+require 'cgi'
+
+module Net #:nodoc:all
+  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

data/lib/scribdresource.rb

@@ -0,0 +1,164 @@
+module Scribd
+  
+  # Describes a remote object that the Scribd API lets you interact with. All
+  # such objects are modeled after the <tt>ActiveRecord</tt> ORM approach.
+  #
+  # The Resource superclass is never directly used; you will interact with
+  # actual Scribd entities like Document and User, which inherit functionality
+  # from this superclass.
+  #
+  # Objects have one or more attributes (also called fields) that can be
+  # accessed directly through synonymous methods. For instance, if your resource
+  # has an attribute +title+, you can get and set the title like so:
+  #
+  #  obj.title #=> "Title"
+  #  obj.title = "New Title"
+  #
+  # The specific attributes that a Document or a User or any other resource has
+  # are not stored locally. They are downloaded remotely whenever a resource is
+  # loaded from the remote server. Thus, you can modify any attribute you want,
+  # though it may or may not have any effect:
+  #
+  #  doc = Scribd::Document.find(:text => 'foo').first
+  #  doc.self_destruct_in = 5.seconds #=> Does not produce error
+  #  doc.save #=> Has no effect, since that attribute doesn't exist. Your document does not explode.
+  #
+  # As shown above, when you make changes to an attribute, these changes are not
+  # immediately reflected remotely. They are only stored locally until such time
+  # as save is called. When you call save, the remote object is updated to
+  # reflect the changes you made in its API instance.
+  
+  class Resource
+    
+    # Initializes instance variables.
+    
+    def initialize(options={})
+      @saved = false
+      @created = false
+      @attributes = Hash.new
+    end
+    
+    # Creates a new instance with the given attributes, saves it immediately,
+    # and returns it. You should call its created? method if you need to verify
+    # that the object was saved successfully.
+    
+    def self.create(options={})
+      obj = new(options)
+      obj.save
+      obj
+    end
+    
+    # Throws NotImplementedError by default.
+    
+    def save
+      raise NotImplementedError, "Cannot save #{self.class.to_s} objects"
+    end
+    
+    # Throws NotImplementedError by default.
+    
+    def self.find(options)
+      raise NotImplementedError, "Cannot find #{self.class.to_s} objects"
+    end
+    
+    # Throws NotImplementedError by default.
+    
+    def destroy
+      raise NotImplementedError, "Cannot destroy #{self.class.to_s} objects"
+    end
+    
+    # Returns true if this document's attributes have been updated remotely, and
+    # thus their local values reflect the remote values.
+    
+    def saved?
+      @saved
+    end
+    
+    # Returns true if this document has been created remotely, and corresponds
+    # to a document on the Scribd website.
+    
+    def created?
+      @created
+    end
+    
+    # Returns the value of an attribute, referenced by string or symbol, or nil
+    # if the attribute cannot be read.
+    
+    def read_attribute(attribute)
+      raise ArgumentError, "Attribute must respond to to_sym" unless attribute.respond_to? :to_sym
+      @attributes[attribute.to_sym]
+    end
+    
+    # Returns a map of attributes to their values, given an array of attributes,
+    # referenced by string or symbol. Attributes that cannot be read are
+    # ignored.
+    
+    def read_attributes(attributes)
+      raise ArgumentError, "Attributes must be listed in an Enumeration" unless attributes.kind_of?(Enumerable)
+      raise ArgumentError, "All attributes must respond to to_sym" unless attributes.all? { |a| a.respond_to? :to_sym }
+      keys = attributes.map(&:to_sym)
+      values = @attributes.values_at(*keys)
+      keys.zip(values).to_hsh
+    end
+    
+    # Assigns values to attributes. Takes a hash that specifies the
+    # attribute-value pairs to update. Does not perform a save. Non-writeable
+    # attributes are ignored.
+    
+    def write_attributes(values)
+      raise ArgumentError, "Values must be specified through a hash of attributes" unless values.kind_of? Hash
+      raise ArgumentError, "All attributes must respond to to_sym" unless values.keys.all? { |a| a.respond_to? :to_sym }
+      @attributes.update values.map { |k,v| [ k.to_sym, v ] }.to_hsh
+    end
+    
+    # Gets or sets attributes for the resource. Any named attribute can be
+    # retrieved for changed through a method call, even if it doesn't exist.
+    # Such attributes will be ignored and purged when the document is saved:
+    #
+    #  doc = Scribd::Document.new
+    #  doc.foobar #=> Returns nil
+    #  doc.foobar = 12
+    #  doc.foobar #=> Returns 12
+    #  doc.save
+    #  doc.foobar #=> Returns nil
+    #
+    # Because of this, no Scribd resource will ever raise NoMethodError.
+    
+    def method_missing(meth, *args)
+      if meth.to_s =~ /(\w+)=/ then
+        raise ArgumentError, "Only one parameter can be passed to attribute=" unless args.size == 1
+        @attributes[$1.to_sym] = args[0]
+      else
+        @attributes[meth]
+      end
+    end
+    
+    # Pretty-print for debugging output of Scribd resources.
+    
+    def inspect #:nodoc:
+      "#<#{self.class.to_s} #{@attributes.select { |k, v| not v.nil? }.collect { |k,v| k.to_s + '=' + v.to_s }.join(', ')}>"
+    end
+    
+    private
+    
+    def load_attributes(xml)
+      @attributes.clear
+      xml.each_element do |element|
+        text = if element.text.nil? or element.text.chomp.strip.empty? then
+          (element.cdatas and not element.cdatas.empty?) ? element.cdatas.first.value : nil
+        else
+          element.text
+        end
+        
+        @attributes[element.name.to_sym] = if element.attributes['type'] == 'integer' then
+          text.to_i
+        elsif element.attributes['type'] == 'float' then
+          text.to_f
+        elsif element.attributes['type'] == 'symbol' then
+          text.to_sym
+        else
+          text
+        end
+      end
+    end
+  end
+end

data/lib/scribduser.rb

@@ -0,0 +1,143 @@
+module Scribd
+  
+  # A user of the Scribd website. API programs can use this class to log in as a
+  # Scribd user, create new user accounts, and get information about the current
+  # user.
+  #
+  # An API program begins by logging into Scribd:
+  #
+  #  user = Scribd::User.login 'login', 'pass'
+  #
+  # You can now access information about this user through direct method calls:
+  #
+  #  user.name #=> 'Real Name'
+  #
+  # If, at any time, you would like to retrieve the Scribd::User instance for
+  # the currently logged-in user, simply call:
+  #
+  #  user = Scribd::API.instance.user
+  #
+  # For information on a user's attributes, please consult the online API
+  # documentation at http://www.scribd.com/publisher/api?method_name=user.login
+  #
+  # You can create a new account with the signup (a.k.a. create) method:
+  #
+  #  user = Scribd::User.signup :username => 'testuser', :password => 'testpassword', :email => your@email.com
+  
+  class User < Resource
+    
+    # Creates a new, unsaved user with the given attributes. You can eventually
+    # use this record to create a new Scribd account.
+    
+    def initialize(options={})
+      super
+      if options[:xml] then
+        load_attributes(options[:xml])
+        @saved = true
+        @created = true
+      else
+        @attributes = options
+      end
+    end
+    
+    # For new, unsaved records, creates a new Scribd user with the provided
+    # attributes, then logs in as that user. Currently modification of existing
+    # Scribd users is not supported. Throws a ResponseError if a remote error
+    # occurs.
+    
+    def save
+      if not created? then
+        response = API.instance.send_request('user.signup', @attributes)
+        xml = response.get_elements('/rsp')[0]
+        load_attributes(xml)
+        API.instance.user = self
+      else
+        raise NotImplementedError, "Cannot update a user once that user's been saved"
+      end
+    end
+    
+    # Returns a list of all documents owned by this user. This list is _not_
+    # backed by the server, so if you add or remove items from it, it will not
+    # make those changes server-side. This also has some tricky consequences
+    # when modifying a list of documents while iterating over it:
+    #
+    #  docs = user.documents
+    #  docs.each(&:destroy)
+    #  docs #=> Still populated, because it hasn't been updated
+    #  docs = user.documents #=> Now it's empty
+    #
+    # Scribd::Document instances returned through this method have more
+    # attributes than those returned by the Scribd::Document.find method. The
+    # additional attributes are documented online at
+    # http://www.scribd.com/publisher/api?method_name=docs.getSettings
+    
+    def documents
+      response = API.instance.send_request('docs.getList', { :session_key => @attributes[:session_key] })
+      documents = Array.new
+      response.elements['/rsp/resultset'].elements.each do |doc|
+        documents << Document.new(:xml => doc, :owner => self)
+      end
+      return documents
+    end
+    
+    # Finds documents owned by this user matching a given query. The parameters
+    # provided to this method are identical to those provided to
+    # Scribd::Document.find.
+    
+    def find_documents(options)
+      return nil unless @attributes[:session_key]
+      Document.find options.merge(:scope => 'user', :session_key => @attributes[:session_key])
+    end
+    
+    # Loads a Scribd::Document by ID. You can only load such documents if they 
+    # belong to this user.
+    
+    def find_document(document_id)
+      return nil unless @attributes[:session_key]
+      response = API.instance.send_request('docs.getSettings', { :doc_id => document_id, :session_key => @attributes[:session_key] })
+      Document.new :xml => response.elements['/rsp'], :owner => self
+    end
+    
+    # Uploads a document to a user's document list. This method takes the
+    # following options:
+    #
+    # +file+:: The location of a file on disk or the URL to a file on the Web
+    # +type+:: The file's type (e.g., "txt" or "ppt"). Optional if the file has
+    #          an extension (like "file.txt").
+    #
+    # There are other options you can specify. For more information, see the
+    # Scribd::Document.save method.
+    
+    def upload(options)
+      raise NotReadyError, "User hasn't been created yet" unless created?
+      Document.create options.merge(:owner => self)
+    end
+    
+    class << self
+      alias_method :signup, :create
+    end
+    
+    # Logs into Scribd using the given username and password. This user will be
+    # used for all subsequent Scribd API calls. You must log in before you can
+    # use protected API functions. Returns the Scribd::User instance for the
+    # logged in user.
+    
+    def self.login(username, password)
+      response = API.instance.send_request('user.login', { :username => username, :password => password })
+      xml = response.get_elements('/rsp')[0]
+      user = User.new(:xml => xml)
+      API.instance.user = user
+      return user
+    end
+    
+    # Returns the +user_id+ attribute.
+    
+    def id
+      self.user_id
+    end
+    
+    def to_s #:nodoc:
+      @attributes[:username]
+    end
+  end
+end

data/sample/01_upload.rb

@@ -0,0 +1,47 @@
+# Example 1 - Uploading a test text file and removing it afterwards.
+
+require 'rubygems'
+require 'rscribd'
+
+# Use your API key / secret here
+api_key = ''
+api_secret = ''
+ 
+# Create a scribd object
+Scribd::API.instance.key = api_key
+Scribd::API.instance.secret = api_secret
+#Scribd::API.instance.debug = true
+
+begin
+  Scribd::User.login 'LOGIN', 'PASSWORD'
+  # Upload the document from a file
+  print "Uploading a document ... "
+
+  doc = Scribd::Document.upload(:file => 'test.txt')
+  puts "Done doc_id=#{doc.id}, doc_access_key=#{doc.access_key}"
+
+  # Poll API until conversion is complete
+  while (doc.conversion_status == 'PROCESSING')
+    puts "Document conversion is processing"
+    sleep(2) # Very important to sleep to prevent a runaway loop that will get your app blocked
+  end
+  puts "Document conversion is complete"
+
+  # Edit various options of the document
+  # Note you can also edit options before your doc is done converting
+  doc.title = 'This is a test doc!'
+  doc.description = "I'm testing out the Scribd API!"
+  doc.access = 'private'
+  doc.language = 'en'
+  doc.license = 'c'
+  doc.tags = 'test,api'
+  doc.show_ads = true
+  doc.save
+
+  # Delete the uploaded document
+  print "Deleting a document ... "
+  doc.destroy
+  puts "Done doc_id=#{doc.id}"
+rescue Scribd::ResponseError => e
+  puts "failed code=#{e.code} error='#{e.message}'"
+end

data/sample/02_user.rb

@@ -0,0 +1,44 @@
+# Example 2 - Signing in as a user, and accessing a user's files.
+
+require 'rubygems'
+require 'rscribd'
+
+# Use your API key / secret here
+api_key = ''
+api_secret = ''
+
+# Edit these to a real Scribd username/password pair
+username = ''
+password = ''
+
+# Create a scribd object
+Scribd::API.instance.key = api_key
+Scribd::API.instance.secret = api_secret
+#Scribd::API.instance.debug = true
+
+begin
+
+  # Login your Scribd API object as a particular user
+  # NOTE: Edit this to the username and password of a real Scribd user
+  user = Scribd::User.login username, password
+
+  docs = user.documents
+
+  puts "User #{user.username} has #{docs.size} docs"
+  if docs.size > 0
+    puts "User's docs:" 
+    for doc in docs
+      puts "#{doc.title}"
+    end
+  end
+
+  results = Scribd::Document.find(:all, :query => 'checklist') # Search over the user's docs for the string 'checklist'
+  puts "Search through docs turned up #{results.size} results:"
+  for doc in results
+    puts "#{doc.title}"
+  end
+  
+
+rescue Scribd::ResponseError => e
+  puts "failed code=#{e.code} error='#{e.message}'"
+end

data/sample/test.txt

@@ -0,0 +1 @@
+This is a simple test text file to try out the neat Scribd API.

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification 
+name: scribd-rscribd
+version: !ruby/object:Gem::Version 
+  version: 1.0.2
+platform: ruby
+authors: 
+- Jared Friedman, Tim Morgan
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-07-09 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: mime-types
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">"
+      - !ruby/object:Gem::Version 
+        version: 0.0.0
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.8.2
+    version: 
+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. For more information on the Scribd platform, visit http://www.scribd.com/publisher
+email: api@scribd.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- Manifest.txt
+- README.txt
+files: 
+- History.txt
+- Manifest.txt
+- README.txt
+- Rakefile
+- lib/scribdapi.rb
+- lib/scribddoc.rb
+- lib/scribderrors.rb
+- lib/scribdmultiparthack.rb
+- lib/scribdresource.rb
+- lib/rscribd.rb
+- lib/scribduser.rb
+- sample/01_upload.rb
+- sample/02_user.rb
+- sample/test.txt
+has_rdoc: true
+homepage: http://github.com/scribd/rscribd
+post_install_message: 
+rdoc_options: 
+- --main
+- README.txt
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: rscribd
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Ruby client library for the Scribd API
+test_files: []
+