crocodoc 1.0.0

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.bundle
+.config
+coverage
+InstalledFiles
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.DS_Store
+
+# YARD artifacts
+.yardoc
+_yardoc
+doc/

data/Gemfile

@@ -0,0 +1,2 @@
+source "http://gems.github.com"
+gemspec

data/README.md

@@ -0,0 +1,195 @@
+# crocodoc-ruby
+
+## Introduction
+
+crocodoc-ruby is a Ruby wrapper for the Crocodoc API.
+The Crocodoc API lets you upload documents and then generate secure and customized viewing sessions for them.
+Our API is based on REST principles and generally returns JSON encoded responses,
+and in Ruby are converted to hashes unless otherwise noted.
+
+## Installation
+You can get the library by cloning or downloading the repo.
+
+To clone:
+
+    git clone git@github.com:crocodoc/crocodoc-ruby.git
+    
+To download:
+
+    wget https://github.com/crocodoc/crocodoc-ruby/zipball/master -O crocodoc-ruby.zip
+    unzip crocodoc-ruby.zip
+    mv crocodoc-crocodoc-ruby-* crocodoc-ruby
+
+Require the library into any of your Ruby files.
+
+If you have the gem installed:
+
+    require 'crocodoc'
+    
+If you have the files locally:
+
+    require_relative /path/to/crocodoc-ruby/crocodoc.rb
+
+Please note that this library also requires that the 'rest-client' gem is installed, and a version of Ruby >= 1.9.
+    
+## Getting Started
+
+You can see a number of examples on how to use this library in examples.rb.
+These examples are interactive and you can run this file to see crocodoc-ruby in action.
+
+To run these examples, open up examples.rb and change this line to show your API token:
+
+    Crocodoc.api_token = 'YOUR_API_TOKEN'
+    
+Save the file, make sure the example-files directory is writeable, and then run examples.rb:
+
+    ruby examples.rb
+    
+You should see 15 examples run with output in your terminal.
+You can inspect the examples.rb code to see each API call being used.
+
+To start using crocodoc-ruby in your code, set your API token:
+
+    Crocodoc.api_token = 'YOUR_API_TOKEN'
+    
+And now you can start using the methods in Crocodoc::Document, Crocodoc::Download, and Crocodoc::Session.
+
+Read on to find out more how to use crocodoc-ruby.
+You can also find more detailed information about our API here:
+https://crocodoc.com/docs/api/
+
+## Using the Crocodoc API Library
+
+### Errors
+
+Errors are handled by throwing exceptions.
+We throw instances of CrocodocError.
+
+Note that any Crocodoc API call can throw an exception.
+When making API calls, put them in a begin/rescue block.
+You can see examples.rb to see working code for each method using begin/rescue blocks.
+
+### Document
+
+These methods allow you to upload, check the status of, and delete documents.
+
+#### Upload
+
+https://crocodoc.com/docs/api/#doc-upload  
+To upload a document, use Crocodoc::Document.upload().
+Pass in a url (as a string) or a file resource object.
+This function returns a UUID of the file.
+
+    // with a url
+    uuid = Crocodoc::Document.upload(url)
+    
+    // with a file
+    file_handle = File.open(file_path, 'r')
+    uuid = Crocodoc::Document.upload(file_handle)
+    
+#### Status
+
+https://crocodoc.com/docs/api/#doc-status  
+To check the status of one or more documents, use Crocodoc::Document.status().
+Pass in the UUID of the file or an array of UUIDS you want to check the status of.
+This function returns a hash containing a "status" string" and a "viewable" boolean.
+If you passed in an array instead of a string, this function returns an array of hashes containing the status for each file.
+
+    // $status contains status['status'] and status['viewable']
+    status = Crocodoc::Document.status(uuid)
+    
+    // statuses contains an array of status hashes
+    statuses = Crocodoc::Document.status([uuid, uuid2])
+    
+#### Delete
+
+https://crocodoc.com/docs/api/#doc-delete  
+To delete a document, use Crocodoc::Document.delete().
+Pass in the UUID of the file you want to delete.
+This function returns a boolean of whether the document was successfully deleted or not.
+
+    deleted  = Crocodoc::Document.delete(uuid)
+    
+### Download
+
+These methods allow you to download documents from Crocodoc in different ways.
+You can download originals, PDFs, extracted text, and thumbnails.
+
+#### Document
+
+https://crocodoc.com/docs/api/#dl-doc  
+To download a document, use Crocodoc::Download.document().
+Pass in the uuid,
+an optional boolean of whether or not the file should be downloaded as a PDF,
+an optional boolean of whether or not the file should be annotated,
+and an optional filter string.
+This function returns the file contents as a string, which you probably want to save to a file.
+
+    // with no optional arguments
+    file = Crocodoc::Download.document(uuid)
+    file_handle.write(file)
+    
+    // with all optional arguments
+    file = Crocodoc::Download.document(uuid, true, true, 'all')
+    file_handle.write(file)
+    
+#### Thumbnail
+
+https://crocodoc.com/docs/api/#dl-thumb  
+To download a thumbnail, use Crocodoc::Download.thumbnail().
+Pass in the uuid and optionally the width and height.
+This function returns the file contents as a string, which you probably want to save to a file.
+
+    // with no optional size arguments
+    thumbnail = Crocodoc::Download.thumbnail(uuid)
+    file_handle.write(thumbnail)
+    
+    // with optional size arguments (width 77, height 100)
+    thumbnail = Crocodoc::Download.thumbnail(uuid, 77, 100)
+    file_handle.write(thumbnail)
+
+#### Text
+
+https://crocodoc.com/docs/api/#dl-text  
+To download extracted text from a document, use Crocodoc::Download.text().
+Pass in the uuid.
+This function returns the extracted text as a string.
+
+    text = Crocodoc::Download.text(uuid)
+    
+### Session
+
+The session method allows you to create a session for viewing documents in a secure manner.
+
+#### Create
+
+https://crocodoc.com/docs/api/#session-create  
+To get a session key, use Crocodoc::Session.create().
+Pass in the uuid and optionally a params hash.
+The params hash can contain an "is_editable" boolean,
+a "user" hash with "id" and "name" fields,
+a "filter" string, a "sidebar" string,
+and booleans for "is_admin", "is_downloadable", "is_copyprotected", and "is_demo".
+This function returns a session key.
+
+    // without optional params
+    session_key = Crocodoc::Session.create(uuid)
+    
+    // with optional params
+    session_key = Crocodoc::Session.create(uuid, {
+        'is_editable' => true,
+        'user' => {
+            'id' => 1,
+            'name' => 'John Crocodile'
+        },
+        'filter' => 'all',
+        'is_admin' => true,
+        'is_downloadable' => true,
+        'is_copyprotected' => false,
+        'is_demo' => false,
+        'sidebar' => 'visible'
+    ))
+    
+## Support
+
+Please use github's issue tracker for API library support.

data/crocodoc.gemspec

@@ -0,0 +1,18 @@
+$:.unshift(File.join(File.dirname(__FILE__), 'lib'))
+
+spec = Gem::Specification.new do |s|
+  s.name = 'crocodoc'
+  s.version = '1.0.0'
+  s.summary = 'Ruby wrapper for the Crocodoc API'
+  s.description = 'The Crocodoc API lets you upload documents and then generate secure and customized viewing sessions for them. See https://crocodoc.com for details.'
+  s.authors = ['Brandon Goldman']
+  s.email = ['brandon.goldman@gmail.com']
+  s.homepage = 'https://crocodoc.com/docs/api/'
+  s.require_paths = %w{lib}
+
+  s.add_dependency('rest-client', '~> 1.4')
+  s.add_dependency('json', '~> 1.1')
+
+  s.files = `git ls-files`.split("\n")
+  s.require_paths = ['lib']
+end

data/examples.rb

@@ -0,0 +1,363 @@
+# = Examples
+
+# Require libraries and set API token
+require 'pathname'
+require_relative 'lib/crocodoc'
+Crocodoc.api_token = 'YOUR_API_TOKEN'
+
+# == Example #1
+# 
+# Upload a file to Crocodoc. We're uploading Form W4 from the IRS by URL.
+puts 'Example #1 - Upload Form W4 from the IRS by URL.'
+form_w4_url = 'http://www.irs.gov/pub/irs-pdf/fw4.pdf'
+print '  Uploading... '
+uuid = nil
+
+begin
+  uuid = Crocodoc::Document.upload(form_w4_url)
+  puts 'success :)'
+  puts '  UUID is ' + uuid
+rescue CrocodocError => e
+  puts 'failed :('
+  puts '  Error Code: ' + e.code
+  puts '  Error Message: ' + e.message
+end
+
+# == Example #2
+# 
+# Check the status of the file from Example #1.
+puts ''
+puts 'Example #2 - Check the status of the file we just uploaded.'
+print '  Checking status... '
+
+begin
+  status = Crocodoc::Document.status(uuid)
+  
+  unless status.has_key? 'error'
+    puts 'success :)'
+    puts '  File status is ' + status['status'] + '.'
+    puts '  File ' + (status['viewable'] ? 'is' : 'is not') + ' viewable.'
+  else
+    puts 'failed :('
+    puts '  Error Message: ' + status['error']
+  end
+rescue CrocodocError => e
+  puts 'failed :('
+  puts '  Error Code: ' + e.code
+  puts '  Error Message: ' + e.message
+end
+
+# == Example #3
+# 
+# Upload another file to Crocodoc. We're uploading Form W4 from the IRS as a PDF.
+puts ''
+puts 'Example #3 - Upload a sample .pdf as a file.'
+uuid2 = nil
+file_path = String(Pathname.new(File.expand_path(__FILE__)).dirname) + '/example-files/form-w4.pdf'
+
+if File.exists? file_path
+  file_handle = File.open(file_path, 'r+')
+  print '  Uploading... '
+
+  begin
+    uuid2 = Crocodoc::Document.upload(file_handle)
+    puts 'success :)'
+    puts '  UUID is ' + uuid2
+  rescue CrocodocError => e
+    puts 'failed :('
+    puts '  Error Code: ' + e.code
+    puts '  Error Message: ' + e.message
+  end
+else
+  puts '  Skipping because the sample pdf can\'t be found.'
+end
+
+# == Example #4
+# 
+# Check the status of both files we uploaded in Examples #1 and #3.
+puts ''
+puts 'Example #4 - Check the status of both files at the same time.'
+print '  Checking statuses... '
+
+begin
+  statuses = Crocodoc::Document.status([uuid, uuid2])
+  
+  if statuses
+    puts 'success :)'
+    
+    unless statuses[0].has_key? 'error'
+      puts '  File #1 status is ' + statuses[0]['status'] + '.'
+      puts '  File #1 ' + (statuses[0]['viewable'] ? 'is' : 'is not') + ' viewable.'
+    else
+      puts '  File #1 failed :('
+      puts '  Error Message: ' . statuses[0]['error']
+    end
+    
+    unless statuses[1].has_key? 'error'
+      puts '  File #2 status is ' + statuses[1]['status'] + '.'
+      puts '  File #2 ' + (statuses[1]['viewable'] ? 'is' : 'is not') + ' viewable.'
+    else
+      puts '  File #2 failed :('
+      puts '  Error Message: ' . statuses[1]['error']
+    end
+  else
+    puts 'failed :('
+    puts '  Statuses were not returned.'
+  end
+rescue CrocodocError => e
+  puts 'failed :('
+  puts '  Error Code: ' + e.code
+  puts '  Error Message: ' + e.message
+end
+
+# == Example #5
+# 
+# Wait ten seconds and check the status of both files again.
+puts ''
+puts 'Example #5 - Wait ten seconds and check the statuses again.'
+print '  Waiting... '
+sleep(10)
+puts 'done.'
+print '  Checking statuses... '
+
+begin
+  statuses = Crocodoc::Document.status([uuid, uuid2])
+  
+  if statuses
+    puts 'success :)'
+    
+    unless statuses[0].has_key? 'error'
+      puts '  File #1 status is ' + statuses[0]['status'] + '.'
+      puts '  File #1 ' + (statuses[0]['viewable'] ? 'is' : 'is not') + ' viewable.'
+    else
+      puts '  File #1 failed :('
+      puts '  Error Message: ' . statuses[0]['error']
+    end
+    
+    unless statuses[1].has_key? 'error'
+      puts '  File #2 status is ' + statuses[1]['status'] + '.'
+      puts '  File #2 ' + (statuses[1]['viewable'] ? 'is' : 'is not') + ' viewable.'
+    else
+      puts '  File #2 failed :('
+      puts '  Error Message: ' . statuses[1]['error']
+    end
+  else
+    puts 'failed :('
+    puts '  Statuses were not returned.'
+  end
+rescue CrocodocError => e
+  puts 'failed :('
+  puts '  Error Code: ' + e.code
+  puts '  Error Message: ' + e.message
+end
+
+# == Example #6
+# 
+# Delete the file we uploaded from Example #1.
+puts ''
+puts 'Example #6 - Delete the first file we uploaded.'
+print '  Deleting... '
+
+begin
+  deleted = Crocodoc::Document.delete(uuid)
+  
+  if deleted
+    puts 'success :)'
+    puts '  File was deleted.'
+  else
+    print 'failed :('
+  end
+rescue CrocodocError => e
+  puts 'failed :('
+  puts '  Error Code: ' + e.code
+  puts '  Error Message: ' + e.message
+end
+
+# == Example #7
+# 
+# Download the file we uploaded from Example #3 as an original
+puts ''
+puts 'Example #7 - Download a file as an original.'
+print '  Downloading... '
+
+begin
+  file = Crocodoc::Download.document(uuid2)
+  filename = String(Pathname.new(File.expand_path(__FILE__)).dirname) + '/example-files/test-original.pdf'
+  file_handle = File.open(filename, 'w')
+  file_handle.write(file)
+  puts 'success :)'
+  puts '  File was downloaded to ' + filename + '.'
+rescue CrocodocError => e
+  puts 'failed :('
+  puts '  Error Code: ' + e.code
+  puts '  Error Message: ' + e.message
+end
+
+# == Example #8
+# 
+# Download the file we uploaded from Example #3 as a PDF
+puts ''
+puts 'Example #8 - Download a file as a PDF.'
+print '  Downloading... '
+
+begin
+  file = Crocodoc::Download.document(uuid2, true)
+  filename = String(Pathname.new(File.expand_path(__FILE__)).dirname) + '/example-files/test.pdf'
+  file_handle = File.open(filename, 'w')
+  file_handle.write(file)
+  puts 'success :)'
+  puts '  File was downloaded to ' + filename + '.'
+rescue CrocodocError => e
+  puts 'failed :('
+  puts '  Error Code: ' + e.code
+  puts '  Error Message: ' + e.message
+end
+
+# == Example #9
+# 
+# Download the file we uploaded from Example #3 with all options
+puts ''
+puts 'Example #9 - Download a file with all options.'
+print '  Downloading... '
+
+begin
+  file = Crocodoc::Download.document(uuid2, true, true, 'all')
+  filename = String(Pathname.new(File.expand_path(__FILE__)).dirname) + '/example-files/test-with-options.pdf'
+  file_handle = File.open(filename, 'w')
+  file_handle.write(file)
+  puts 'success :)'
+  puts '  File was downloaded to ' + filename + '.'
+rescue CrocodocError => e
+  puts 'failed :('
+  puts '  Error Code: ' + e.code
+  puts '  Error Message: ' + e.message
+end
+
+# == Example #10
+# 
+# Download the file we uploaded from Example #3 as a default thumbnail
+puts ''
+puts 'Example #10 - Download a default thumbnail from a file.'
+print '  Downloading... '
+
+begin
+  file = Crocodoc::Download.thumbnail(uuid2)
+  filename = String(Pathname.new(File.expand_path(__FILE__)).dirname) + '/example-files/thumbnail.png'
+  file_handle = File.open(filename, 'w')
+  file_handle.write(file)
+  puts 'success :)'
+  puts '  File was downloaded to ' + filename + '.'
+rescue CrocodocError => e
+  puts 'failed :('
+  puts '  Error Code: ' + e.code
+  puts '  Error Message: ' + e.message
+end
+
+# == Example #11
+# 
+# Download the file we uploaded from Example #3 as a large thumbnail
+puts ''
+puts 'Example #11 - Download a large thumbnail from a file.'
+print '  Downloading... '
+
+begin
+  file = Crocodoc::Download.thumbnail(uuid2, 250, 250)
+  filename = String(Pathname.new(File.expand_path(__FILE__)).dirname) + '/example-files/thumbnail-large.png'
+  file_handle = File.open(filename, 'w')
+  file_handle.write(file)
+  puts 'success :)'
+  puts '  File was downloaded to ' + filename + '.'
+rescue CrocodocError => e
+  puts 'failed :('
+  puts '  Error Code: ' + e.code
+  puts '  Error Message: ' + e.message
+end
+
+# == Example #12
+# 
+# Download extracted text from the file we uploaded from Example #3
+puts ''
+puts 'Example #12 - Download extracted text from a file.'
+print '  Downloading... '
+
+begin
+  file = Crocodoc::Download.text(uuid2)
+  filename = String(Pathname.new(File.expand_path(__FILE__)).dirname) + '/example-files/text.txt'
+  file_handle = File.open(filename, 'w')
+  file_handle.write(file)
+  puts 'success :)'
+  puts '  File was downloaded to ' + filename + '.'
+rescue CrocodocError => e
+  puts 'failed :('
+  puts '  Error Code: ' + e.code
+  puts '  Error Message: ' + e.message
+end
+
+# == Example #13
+# 
+# Create a session key for the file we uploaded from Example #3 with default
+# options.
+puts ''
+puts 'Example #13 - Create a session key for a file with default options.'
+print '  Creating... '
+session_key = nil
+
+begin
+  session_key = Crocodoc::Session.create(uuid2)
+  puts 'success :)'
+  puts '  The session key is ' + session_key + '.'
+rescue CrocodocError => e
+  puts 'failed :('
+  puts '  Error Code: ' + e.code
+  puts '  Error Message: ' + e.message
+end
+
+# == Example #14
+# 
+# Create a session key for the file we uploaded from Example #3 all of the
+# options.
+puts ''
+puts 'Example #14 - Create a session key for a file with all of the options.'
+print '  Creating...'
+session_key = nil
+
+begin
+  user = {'id' => 1,
+          'name' => 'John Crocodoc'}
+  session_key = Crocodoc::Session.create(uuid2, {'isEditable' => true,
+                                                 'user' => user,
+                                                 'filter' => 'all',
+                                                 'is_admin' => true,
+                                                 'is_downloadable' => true,
+                                                 'is_copyprotected' => false,
+                                                 'is_demo' => false,
+                                                 'sidebar' => 'visible'})
+  puts 'success :)'
+  puts '  The session key is ' + session_key + '.'
+rescue CrocodocError => e
+  puts 'failed :('
+  puts '  Error Code: ' + e.code
+  puts '  Error Message: ' + e.message
+end
+
+# == Example #15
+# 
+# Delete the file we uploaded from Example #2.
+puts ''
+puts 'Example #15 - Delete the second file we uploaded.'
+print '  Deleting... '
+
+begin
+  deleted = Crocodoc::Document.delete(uuid2)
+  
+  if deleted
+    puts 'success :)'
+    puts '  File was deleted.'
+  else
+    print 'failed :('
+  end
+rescue CrocodocError => e
+  puts 'failed :('
+  puts '  Error Code: ' + e.code
+  puts '  Error Message: ' + e.message
+end

data/lib/crocodoc.rb

@@ -0,0 +1,180 @@
+# require core functionality
+require 'json'
+require 'rest-client'
+
+# require our exception class
+require_relative 'crocodoc_error'
+
+# require the different crocodoc clients
+require_relative 'crocodoc/document'
+require_relative 'crocodoc/download'
+require_relative 'crocodoc/session'
+
+module Crocodoc
+  # The developer's Crocodoc API token
+  @@api_token = nil
+  
+  # The default protocol (Crocodoc uses HTTPS)
+  @@protocol = 'https'
+  
+  # The default host
+  @@host = 'crocodoc.com'
+  
+  # The default base path on the server where the API lives
+  @@base_path = '/api/v2'
+  
+  # Set the API token
+  def self.api_token=(api_token)
+    @@api_token = api_token
+  end
+  
+  # Get the API token
+  def self.api_token
+    @@api_token
+  end
+  
+  # Set the protocol
+  def self.protocol=(protocol)
+    @@protocol = protocol
+  end
+  
+  # Get the protocol
+  def self.protocol
+    @@protocol
+  end
+  
+  # Set the host
+  def self.host=(host)
+    @@host = host
+  end
+  
+  # Get the host
+  def self.host
+    @@host
+  end
+  
+  # Set the base path
+  def self.base_path=(base_path)
+    @@base_path = base_path
+  end
+  
+  # Get the base path
+  def self.base_path
+    @@base_path
+  end
+  
+  # Handle an error. We handle errors by throwing an exception.
+  # 
+  # @param [String] error An error code representing the error
+  #   (use_underscore_separators)
+  # @param [String] client Which API client the error is being called from
+  # @param [String] method Which method the error is being called from
+  # @param [Hash<String,>, String] response This is a hash of the response,
+  #   usually from JSON, but can also be a string
+  # 
+  # @raise [CrocodocError]
+  def self._error(error, client, method, response)
+    message = self.name + ': [' + error + '] ' + client + '.' + String(method) + "\r\n\r\n"
+    response = JSON.generate(response) if response.is_a? Hash
+    message += response
+    raise CrocodocError.new(message, error)
+  end
+  
+  # Make an HTTP request. Some of the params are polymorphic - get_params and
+  # post_params. 
+  # 
+  # @param [String] path The path on the server to make the request to
+  #   relative to the base path
+  # @param [String] method This is just an addition to the path, for example,
+  #   in "/documents/upload" the method would be "upload"
+  # @param [Hash<String, String>] get_params A hash of GET params to be added
+  #   to the URL
+  # @param [Hash<String, String>] post_params A hash of GET params to be added
+  #   to the URL
+  # @param [Boolean] is_json Should the file be converted from JSON? Defaults to
+  #   true.
+  # 
+  # @return [Hash<String,>, String] The response hash is usually converted from
+  #   JSON, but sometimes we just return the raw response from the server
+  # @raise [CrocodocError]
+  def self._request(path, method, get_params, post_params, is_json=true)
+    url = @@protocol + '://' + @@host + @@base_path + path + method
+
+    # add the API token to get_params
+    get_params = {} unless get_params
+    get_params['token'] = @@api_token
+    
+    # add the API token to post_params
+    if post_params and post_params.length > 0
+      # add the API token to post_params
+      post_params['token'] = @@api_token
+    end
+
+    result = nil
+    http_code = nil
+    
+    if post_params && post_params.length > 0
+      response = RestClient.post(url, post_params, params: get_params){|response, request, result| result }
+      result = RestClient::Request.decode(response['content-encoding'], response.body)
+      http_code = Integer(response.code)
+    else
+      response = RestClient.get(url, params: get_params){|response, request, result| result }
+      result = RestClient::Request.decode(response['content-encoding'], response.body)
+      http_code = Integer(response.code)
+    end
+    
+    if is_json
+      json_decoded = false
+      
+      if result == 'true'
+        json_decoded = true
+      elsif result == 'false'
+        json_decoded = false
+      else
+        json_decoded = JSON.parse(result)
+      end
+  
+      if json_decoded == false
+        return self._error('server_response_not_valid_json', self.name, __method__, {
+          response => result,
+          get_params => get_params,
+          post_params => post_params
+        })
+      end
+      
+      if json_decoded.is_a? Hash and json_decoded.has_key? 'error'
+        return self._error(json_decoded['error'], self.name, __method__, {
+          get_params => get_params,
+          post_params => post_params
+        })
+      end
+        
+      result = json_decoded
+    end
+
+    http_4xx_error_codes = {'400' => 'bad_request',
+                            '401' => 'unauthorized',
+                            '404' => 'not_found',
+                            '405' => 'method_not_allowed'}
+    
+    if http_4xx_error_codes.has_key? http_code
+      error = 'server_error_' + http_code + '_' + http_4xx_error_codes[http_code]
+      return self._error(error, self.name, __method__, {
+        url => url,
+        get_params => get_params,
+        postParams => post_params
+      })
+    end
+    
+    if http_code >= 500 and http_code < 600
+      error = 'server_error_' + http_code + '_unknown'
+      return self._error(error, self.name, __method__, {
+        url => url,
+        get_params => get_params,
+        post_params => post_params
+      })
+    end
+    
+    result
+  end
+end

data/lib/crocodoc/document.rb

@@ -0,0 +1,75 @@
+module Crocodoc
+  # Provides access to the Crocodoc Document API. The Document API is used for
+  # uploading, checking status, and deleting documents.
+  class Document
+    # The Document API path relative to the base API path
+    @@path = '/document/'
+    
+    # Set the path
+    def self.path=(path)
+      @@path = path
+    end
+    
+    # Get the path
+    def self.path
+      @@path
+    end
+    
+    # Delete a file on Crocodoc by UUID.
+    # 
+    # @param [String] uuid The uuid of the file to delete
+    # 
+    # @return [Boolean] Was the file deleted?
+    # @raise [CrocodocError]
+    def self.delete(uuid)
+      post_params = {'uuid' => uuid}
+      Crocodoc._request(self.path, 'delete', nil, post_params)
+    end
+    
+    # Check the status of a file on Crocodoc by UUID. This method is
+    # polymorphic and can take an array of UUIDs and return an array of status
+    # hashes about those UUIDs, or can also take a one UUID string and return
+    # one status hash for that UUID.
+    # 
+    # @param [Array<String>, String] uuids An array of the uuids of the file to
+    #   check the status of - this can also be a single uuid string
+    # 
+    # @return [Array<Hash<String,>>, Hash<String,>] An array of hashes (or just
+    #   an hash if you passed in a string) of the uuid, status, and viewable
+    #   bool, or an array of the uuid and an error
+    # @raise [CrocodocError]
+    def self.status(uuids)
+      is_single_uuid = uuids.is_a? String
+      uuids = [uuids] if is_single_uuid
+      get_params = {'uuids' => uuids.join(',')}
+      response = Crocodoc._request(self.path, 'status', get_params, nil)
+      is_single_uuid ? response[0] : response
+    end
+  	
+  	# Upload a file to Crocodoc with a URL.
+    # 
+    # @param url_or_file [String, File] The url of the file to upload or a file resource
+    # 
+    # @return [String] The uuid of the newly-uploaded file
+    # @raise [CrocodocError]
+    def self.upload(url_or_file)
+      post_params = {}
+      
+      if url_or_file.is_a? String
+        post_params['url'] = url_or_file
+      elsif url_or_file.is_a? File
+      	post_params['file'] = url_or_file
+      else
+      	return Crocodoc::_error('invalid_url_or_file_param', self.name, __method__, nil)
+      end
+      
+      response = Crocodoc::_request(self.path, 'upload', nil, post_params)
+      
+      unless response.has_key? 'uuid'
+      	return Crocodoc::_error('missing_uuid', self.name, __method__, response)
+      end
+      
+      response['uuid']
+    end
+  end
+end

data/lib/crocodoc/download.rb

@@ -0,0 +1,74 @@
+module Crocodoc
+  # Provides access to the Crocodoc Download API. The Download API is used for
+  # downloading an original of a document, a PDF of a document, a thumbnail of a
+  # document, and text extracted from a document.
+  class Download
+    # The Download API path relative to the base API path
+    @@path = '/download/'
+    
+    # Set the path
+    def self.path=(path)
+      @@path = path
+    end
+    
+    # Get the path
+    def self.path
+      @@path
+    end
+    
+    # Download a document's original file from Crocodoc. The file can
+    # optionally be downloaded as a PDF, as another filename, with
+    # annotations, and with filtered annotations.
+    # 
+    # @param [String] uuid The uuid of the file to download
+    # @param [Boolean] is_pdf Should the file be downloaded as a PDF?
+    # @param [Boolean] is_annotated Should the file be downloaded with annotations?
+    # @param [String, Array<String>] filter Which annotations should be
+    #   included if any - this is usually a string, but could also be an array
+    #   if it's a comma-separated list of user IDs as the filter
+    # 
+    # @return [String] The downloaded file contents as a string
+    # @raise CrocodocError
+    def self.document(uuid, is_pdf=false, is_annotated=false, filter=nil)
+      get_params = {'uuid' => uuid}
+      get_params['pdf'] = 'true' if is_pdf
+      get_params['annotated'] = 'true' if is_annotated
+      
+      if filter
+        filter = filter.join(',') if filter.is_a? Array
+        get_params['filter'] = filter
+      end
+      
+      Crocodoc._request(self.path, 'document', get_params, nil, false)
+    end
+    
+    # Download a document's extracted text from Crocodoc.
+    # 
+    # @param [String] uuid The uuid of the file to extract text from
+    # 
+    # @return [String] The file's extracted text
+    # @raise CrocodocError
+    def self.text(uuid)
+      get_params = {'uuid' => uuid}
+      Crocodoc._request(self.path, 'text', get_params, nil, false)
+    end
+  
+    # Download a document's thumbnail from Crocodoc with an optional size.
+    # 
+    # @param [String] uuid The uuid of the file to download the thumbnail from
+    # @param [Integer] width The width you want the thumbnail to be
+    # @param [Integer] height The height you want the thumbnail to be
+    # 
+    # @return [String] The downloaded thumbnail contents
+    # @raise CrocodocError
+    def self.thumbnail(uuid, width=nil, height=nil)
+      get_params = {'uuid' => uuid}
+    
+      if width != nil and height != nil
+        get_params['size'] = String(width) + 'x' + String(height)
+      end
+    
+      Crocodoc._request(self.path, 'thumbnail', get_params, nil, false)
+    end
+  end
+end

data/lib/crocodoc/session.rb

@@ -0,0 +1,97 @@
+module Crocodoc
+  # Provides access to the Crocodoc Session API. The Session API is used to
+  # to create sessions for specific documents that can be used to view a
+  # document using a specific session-based URL.
+  class Session
+    # The Session API path relative to the base API path
+    @@path = '/session/'
+    
+    # Set the path
+    def self.path=(path)
+      @@path = path
+    end
+    
+    # Get the path
+    def self.path
+      @@path
+    end
+    
+    # Create a session for a specific document by UUID that is optionally
+    # editable and can use user ID and name info from your application,
+    # can filter annotations, can grant admin permissions, can be
+    # downloadable, can be copy-protected, and can prevent changes from being
+    # persisted.
+    # 
+    # @param [String] uuid The uuid of the file to create a session for
+    # @param [Hash<String,>] params A hash representing:
+    #   [Boolean] 'is_editable' Can users create annotations and comments while
+    #     viewing the document with this session key?
+    #   [Hash<String, String>] 'user' A hash with keys "id" and "name"
+    #     representing a user's unique ID and name in your application; "id"
+    #     must be a non-negative signed 32-bit integer; this field is required
+    #     if is_editable is true
+    #   [String, Array<String>] 'filter' Which annotations should be included
+    #     if any - this is usually a string, but could also be an array if it's
+    #     a comma-separated list of user IDs as the filter
+    #   [Boolean] 'is_admin' Can users modify or delete any annotations or comments
+    #     belonging to other users?
+    #   [Boolean] 'is_downloadable' Can users download the original document?
+    #   [Boolean] 'is_copyprotected' Can text be selected in the document?
+    #   [Boolean] 'is_demo' Should we prevent any changes from being persisted?
+    #   [String] 'sidebar' Sets if and how the viewer sidebar is included
+    # 
+    # @return [String] A unique session key for the document
+    # @raise [CrocodocError]
+    def self.create(uuid, params = {})
+      post_params = {'uuid' => uuid}
+
+      if params.has_key? 'is_editable'
+        post_params['editable'] = params['is_editable'] ? 'true' : 'false'
+      end
+      
+      if (
+        params.has_key? 'user' \
+        and params['user'] \
+        and params['user'].is_a? Hash \
+        and params['user'].has_key? 'id' \
+        and params['user'].has_key? 'name' \
+      )
+        post_params['user'] = String(params['user']['id']) + ',' + params['user']['name']
+      end
+      
+      if params.has_key? 'filter'
+        if params['filter'].is_a? Array
+          params['filter'] = params['filter'].join(',')
+        end
+        
+        post_params['filter'] = params['filter']
+      end
+      
+      if params.has_key? 'is_admin'
+        post_params['admin'] = params['is_admin'] ? 'true' : 'false'
+      end
+      
+      if params.has_key? 'is_downloadable'
+        post_params['downloadable'] = params['is_downloadable'] ? 'true' : 'false'
+      end
+      
+      if params.has_key? 'is_copyprotected'
+        post_params['copyprotected'] = params['is_copyprotected'] ? 'true' : 'false'
+      end
+      
+      if params.has_key? 'is_demo'
+        post_params['demo'] = params['is_demo'] ? 'true' : 'false'
+      end
+
+      post_params['sidebar'] = params['sidebar'] if params.has_key? 'sidebar'
+      
+      session = Crocodoc._request(self.path, 'create', nil, post_params)
+      
+      unless session.is_a? Hash and session.has_key? 'session'
+        return Crocodoc._error('missing_session_key', self.name, __method__, session)
+      end
+      
+      session['session']
+    end
+  end
+end

data/lib/crocodoc_error.rb

@@ -0,0 +1,16 @@
+# CrocodocError extends the default exception class.
+# It adds a code field.
+class CrocodocError < Exception
+  # An error code string
+  @code = nil
+  
+  # Get the error code
+  def code
+    @code
+  end
+
+  def initialize(message, code)
+    @message = message
+    @code = code
+  end
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification 
+name: crocodoc
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: 
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Brandon Goldman
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-10-19 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rest-client
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 1
+        - 4
+        version: "1.4"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: json
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 13
+        segments: 
+        - 1
+        - 1
+        version: "1.1"
+  type: :runtime
+  version_requirements: *id002
+description: The Crocodoc API lets you upload documents and then generate secure and customized viewing sessions for them. See https://crocodoc.com for details.
+email: 
+- brandon.goldman@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- README.md
+- crocodoc.gemspec
+- example-files/form-w4.pdf
+- examples.rb
+- lib/crocodoc.rb
+- lib/crocodoc/document.rb
+- lib/crocodoc/download.rb
+- lib/crocodoc/session.rb
+- lib/crocodoc_error.rb
+homepage: https://crocodoc.com/docs/api/
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.7.2
+signing_key: 
+specification_version: 3
+summary: Ruby wrapper for the Crocodoc API
+test_files: []
+