doc_raptor 0.1.6 → 0.2.0

data/Changelog.md

@@ -0,0 +1,31 @@
+# DocRaptor gem Change Log
+
+## doc_raptor 0.2.0
+* tests!
+* added a create! method which will raise an exception when doc creation fails
+* added a list_docs! method which will raise an exception when doc listing fails
+* added a status! method which will raise an exception when getting an async status fails
+* added a download! method which will raise an exception when getting an async status fails
+
+## doc_raptor 0.1.6
+* allow the gem to be used outside of places with activesupport
+
+## doc_raptor 0.1.5
+* fix bug caused by activesupport safebuffers in rails ~3.0.6 and up
+
+## doc_raptor 0.1.4
+* add support for creating async jobs
+
+## doc_raptor 0.1.3
+* if a block is given to "create", make the value the block returns be the
+  value create returns
+* add list_doc method, for the new api call to list created documents
+
+## doc_raptor 0.1.2
+* add support for the the document_url parameter to create
+
+## doc_raptor 0.1.1
+* reduce httparty requirement to 0.4.3
+
+## doc_raptor 0.1
+* Initial release

data/README.md

@@ -9,40 +9,54 @@ This is a Ruby gem providing a simple wrapper around the DocRaptor API. DocRapto
 The gem will look for your api key in the ENV variable "DOCRAPTOR_API_KEY".  If it is 
 not there, you can set it directly by calling:
 
-    DocRaptor.api_key "My API Key Here"
+```ruby
+DocRaptor.api_key "My API Key Here"
+```
 
-Once an API key is set, you can create documents by calling:
+Once an API key is set, you can create a PDF document by calling:
 
-    DocRaptor.create(:document_content => content, :document_type => "pdf", :test => false, :async => false, :callback_url => nil)
+```ruby
+DocRaptor.create(:document_content => content)
+```
 
-This will return an HTTParty respsonse object, the body of which will be the new file 
-(or errors, if the request was not valid).  You can pass in "pdf" or "xls" as the
-:document_type - default is pdf.  This determines the type of file that DocRaptor will create.
-You can pass in true or false for :test - default is false - and this turns on or off
-test mode for DocRaptor.  You can pass in true or false for :async - default is false - and 
-this submits the document request to be processed asynchronously. If the document is processed 
-asynchronously, a status id will be returned as opposed to the contents of the document. You can 
-then use <METHOD NAME> to get the status of the document. You can pass in a URL to :callback_url 
-to be called once an asynchronous job is complete.  It will be passed a value of "download_url" 
-which will contain a URL that when visited will provide you with your document.  This option 
-does nothing if :async is not true.  The only required parameter is :document_content, which 
-should be a string of html - this will be what DocRaptor turns into your document.
+You might want to set other options in that hash:
 
-The create call can also take a block, like so:
+* `:document_content` - a string containing the content for creating the document
+* `:document_url` - a url to visit to get the content for creating the document
+* `:document_type` - "pdf" or "xls"; controls the type of document generated; default is "pdf"
+* `:name` - an identifier you can use for the document; shows up in doc logs; default is "default"
+* `:test` - test mode flag; set to true to while doing testing so the docs won't count against your monthly count; default is false
+* `:async` - create the document asynchonously; default is false
+* `:callback_url` - a url that we will hit with a status once the asynchronous document has been fully processed 
+* `:prince_options` - see http://docraptor.com/documentation#pdf_options (PDFs only)
 
-    DocRaptor.create(:document_content => content) do |file, response|
-      #file is a tempfile holding the response body
-      #reponse is the HTTParty response object
-    end 
+The only required parameter is one of `:document_content` or `:document_url`.
+
+`create` will return an HTTParty response object, the body of which will be the new file (or errors, if the request was not valid).
+
+`create!` will raise an exception instead of return errors if there is a failure of any sort in the document generation process. It otherwise works in the same way as `create`.
+
+If the document is processed asynchronously, a status id will be returned as opposed to the contents of the document. You can then use <METHOD NAME> to get the status of the document. You can pass in a URL to `:callback_url` to be called once an asynchronous job is complete.  It will be passed a value of `download_url` which will contain a URL that when visited will provide you with your document.  This option does nothing if `:async` is not true.
+
+The `create` call can also take a block, like so:
+
+```ruby
+DocRaptor.create(:document_content => content) do |file, response|
+  #file is a tempfile holding the response body
+  #reponse is the HTTParty response object
+end 
+```
 
 To get the status of an async request, you can call:
-  
-    # uses the id of the most recently created async job
-    DocRaptor.status
-    # query some other async job and make it the "active" async job for the DocRaptor class
-    DocRaptor.status(status_id)
 
-status_id is the value returned from DocRaptor.create when :async is true.  If you have 
+```ruby  
+# uses the id of the most recently created async job
+DocRaptor.status
+# query some other async job and make it the "active" async job for the DocRaptor class
+DocRaptor.status(status_id)
+```
+
+`status_id` is the value returned from `DocRaptor.create` when `:async` is true.  If you have 
 just created a document, status_id defaults to the last status_id received from DocRaptor.
 This will return a hash containing, at the very least, a key of "status" with a value of 
 one of the following: { "completed", "failed", "killed", "queued", "working" }.  If the 
@@ -60,17 +74,14 @@ for the failure to generate your document.
 To download an async document, you can visit the URL (download_url) provided via the status 
 function or you can call:
 
-    # uses the key of the most recently checked async job which is complete
-    DocRaptor.download
-    # use some other complete doc's download key
-    DocRaptor.download(download_key)
-
+```ruby
+# uses the key of the most recently checked async job which is complete
+DocRaptor.download
+# use some other complete doc's download key
+DocRaptor.download(download_key)
+```
 
-download_key is the value from the status hash of a call to DocRaptor.status of a 
-completed job.  If you have just checked the status of a document and it is completed, 
-download_key defaults to that of the document you just checked.  The download function 
-works like DocRaptor.create in that you get back either an HTTParty response object or 
-you can give it a block.
+`download_key` is the value from the status hash of a call to DocRaptor.status of a completed job.  If you have just checked the status of a document and it is completed, `download_key` defaults to that of the document you just checked.  The download function works like DocRaptor.create in that you get back either an HTTParty response object or you can give it a block.
 
 ## Examples ###################################################################
 Check the examples directory for some simple examples. To make them work, you will need to have the docraptor gem installed (via bundler or gem install).

data/lib/doc_raptor.rb

@@ -1,28 +1,66 @@
 require "httparty"
 require "tempfile"
 
+module DocRaptorError
+  class NoApiKeyProvidedError < RuntimeError; end
+  class NoContentError < ArgumentError; end
+end
+
+module DocRaptorException
+  class DocRaptorRequestException < StandardError
+    attr_accessor :status_code
+    attr_accessor :message
+    def initialize(message, status_code)
+      self.message = message
+      self.status_code = status_code
+      super message
+    end
+
+    def to_s
+      "#{self.class.name}\nHTTP Status: #{status_code}\nReturned: #{message}"
+    end
+
+    def inspect
+      self.to_s
+    end
+  end
+  class DocumentCreationFailure < DocRaptorRequestException; end
+  class DocumentListingFailure < DocRaptorRequestException; end
+  class DocumentStatusFailure < DocRaptorRequestException; end
+  class DocumentDownloadFailure < DocRaptorRequestException; end
+end
+
 class DocRaptor
   include HTTParty
   
   def self.api_key(key = nil)
-    return default_options[:api_key] unless key
-    default_options[:api_key] = key
+    default_options[:api_key] = key ? key : default_options[:api_key] || ENV["DOCRAPTOR_API_KEY"]
+    default_options[:api_key] || raise(DocRaptorError::NoApiKeyProvidedError.new("No API key provided"))
+  end
+
+  def self.create!(options = {})
+    raise ArgumentError.new "please pass in an options hash" unless options.is_a? Hash
+    self.create(options.merge({:raise_exception_on_failure => true}))
   end
 
   # when given a block, hands the block a TempFile of the resulting document
   # otherwise, just returns the response
   def self.create(options = { })
+    raise ArgumentError.new "please pass in an options hash" unless options.is_a? Hash
     if options[:document_content].blank? && options[:document_url].blank?
-      raise "must supply :document_content or :document_url" 
+      raise DocRaptorError::NoContentError.new("must supply :document_content or :document_url")
     end
-    
+
     default_options = { 
-      :name             => "default",
-      :document_type    => "pdf",
-      :test             => false,
-      :async            => false
+      :name                       => "default",
+      :document_type              => "pdf",
+      :test                       => false,
+      :async                      => false,
+      :raise_exception_on_failure => false
     }
     options = default_options.merge(options)
+    raise_exception_on_failure = options[:raise_exception_on_failure]
+    options.delete :raise_exception_on_failure
 
     query = { }
     if options[:async]
@@ -41,6 +79,10 @@ class DocRaptor
 
     response = post("/docs", :body => {:doc => options}, :basic_auth => { :username => api_key }, :query => query)
 
+    if raise_exception_on_failure && !response.success?
+      raise DocRaptorException::DocumentCreationFailure.new response.body, response.code
+    end
+
     if block_given?
       ret_val = nil
       Tempfile.open("docraptor") do |f|
@@ -58,19 +100,40 @@ class DocRaptor
     end
   end
   
+  def self.list_docs!(options = { })
+    raise ArgumentError.new "please pass in an options hash" unless options.is_a? Hash
+    self.list_docs(options.merge({:raise_exception_on_failure => true}))
+  end
+
   def self.list_docs(options = { })
+    raise ArgumentError.new "please pass in an options hash" unless options.is_a? Hash
     default_options = { 
       :page     => 1,
-      :per_page => 100
+      :per_page => 100,
+      :raise_exception_on_failure => false
     }
     options = default_options.merge(options)
-    
-    get("/docs", :query => options, :basic_auth => { :username => api_key })
+    raise_exception_on_failure = options[:raise_exception_on_failure]
+    options.delete :raise_exception_on_failure
+
+    response = get("/docs", :query => options, :basic_auth => { :username => api_key })
+    if raise_exception_on_failure && !response.success?
+      raise DocRaptorException::DocumentListingFailure.new response.body, response.code
+    end
+    response
   end
-  
-  def self.status(id = self.status_id)
+
+  def self.status!(id = self.status_id)
+    self.status(id, true)
+  end
+
+  def self.status(id = self.status_id, raise_exception_on_failure = false)
     response = get("/status/#{id}", :basic_auth => { :username => api_key }, :output => 'json')
 
+    if raise_exception_on_failure && !response.success?
+      raise DocRaptorException::DocumentStatusFailure.new response.body, response.code
+    end
+
     json = response.parsed_response
     if json['status'] == 'completed'
       self.download_key = json['download_url'].match(/.*?\/download\/(.+)/)[1]
@@ -79,8 +142,17 @@ class DocRaptor
     json
   end
 
-  def self.download(key = self.download_key)
+  def self.download!(key = self.download_key)
+    self.download(key, true)
+  end
+
+  def self.download(key = self.download_key, raise_exception_on_failure = false)
     response = get("/download/#{key}")
+
+    if raise_exception_on_failure && !response.success?
+      raise DocRaptorException::DocumentDownloadFailure.new response.body, response.code
+    end
+
     if block_given?
       ret_val = nil
       Tempfile.open("docraptor") do |f|
@@ -102,6 +174,4 @@ class DocRaptor
   end
 
   base_uri ENV["DOCRAPTOR_URL"] || "https://docraptor.com/"
-  api_key  ENV["DOCRAPTOR_API_KEY"]
-  
 end

metadata

@@ -5,9 +5,9 @@ version: !ruby/object:Gem::Version
   prerelease: 
   segments: 
   - 0
-  - 1
-  - 6
-  version: 0.1.6
+  - 2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Michael Kuehl
@@ -45,6 +45,7 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
+- Changelog.md
 - README.md
 - MIT-LICENSE
 - lib/doc_raptor.rb