docraptor 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: a3c994ce2ece25936f437a269f823e57a27f3f3c
-  data.tar.gz: ef3483cd3a4c6edb339776e7ce3a7519624ca203
+SHA256:
+  metadata.gz: 1d6b898db0c2631364545a4da3f3a87ef8a249e7e1db737091e42a8095dc2ba4
+  data.tar.gz: 38cc4dd86eb0ae69502ee42c6bdd8cfc1715f8b9b425aa15c4a8089a3edaa609
 SHA512:
-  metadata.gz: 6803e9c81c3ba4075d314d0d5f7553c61de81281452a1cb42577da971de35debea9561d358de2657879665bc8a98b1efa82cd333df3b9e8c8742617c91d9e2c1
-  data.tar.gz: a45210b3f371f1bc13a37fa25f08135647e73a69c39eb58ba90ff81b488612a61fe130b2a0261689c7b87d3b3f70f28b57e26de8196557f508106fc774d06513
+  metadata.gz: 648892ceb32bc298f8fe5689873212106f8059d47b009164d69ccec923a8437e2209e9f7a4d30de0bda430a1a5bb260ab34133797a3a8d796b3b515119120c58
+  data.tar.gz: 1479aabfe153182ef3e0afc66b9c7e5105a2c7873cbe3fe640c6078411895dc30bbb17d58568d22db55a3383f542c2feb9ad140c4ac054de9c58f89244adeb6f

data/.gitignore

@@ -29,6 +29,7 @@ Gemfile.lock
 .ruby-version
 .ruby-gemset
 .rvmrc
+.rubocop.yml
 
 ## Ignore dumb OSX files
 .DS_Store
@@ -38,4 +39,7 @@ Thumbs.db
 swagger-codegen
 
 ## Ignore dumb emacs files
-*~
+*~
+
+## Ignore files that contain special keys
+.docraptor_key

data/.swagger-codegen/VERSION

@@ -1 +1 @@
-2.2.3
+2.4.14

data/.swagger-revision

@@ -1 +1 @@
-v2.2.3
+v2.4.14

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+### 1.4.0 [July 31, 2020]
+* add support for hosted documents
+* upgrade to latest swagger 2.4.14
+
 ### 1.3.0 [November 21, 2017]
 * Added support for `prince_options[pdf_title]` and `ignore_console_messages` options
 

data/Gemfile

@@ -3,5 +3,5 @@ source 'https://rubygems.org'
 gemspec
 
 group :development, :test do
-  gem 'rake', '~> 12.0.0'
+  gem 'rake', '~> 12.3.3'
 end

data/docraptor.gemspec

@@ -1,14 +1,14 @@
 # -*- encoding: utf-8 -*-
-#
+
 =begin
-#DocRaptor v1
+#DocRaptor
 
 #A native client library for the DocRaptor HTML to PDF/XLS service.
 
-OpenAPI spec version: 1.3.0
+OpenAPI spec version: 1.4.0
 
 Generated by: https://github.com/swagger-api/swagger-codegen.git
-Swagger Codegen version: 2.2.3
+Swagger Codegen version: 2.4.14
 
 =end
 
@@ -24,7 +24,7 @@ Gem::Specification.new do |s|
   s.homepage    = "https://github.com/docraptor/docraptor-ruby"
   s.summary     = "A wrapper for the DocRaptor HTML to PDF/XLS service."
   s.description = "A native client library for the DocRaptor HTML to PDF/XLS service."
-  s.license     = "MIT"
+  s.license     = 'MIT'
   s.required_ruby_version = ">= 1.9"
 
   s.add_runtime_dependency 'typhoeus', '~> 1.0', '>= 1.0.1'
@@ -44,7 +44,7 @@ Gem::Specification.new do |s|
   # </added> : if the above lines are missing in the gemspec, then
   # the matcher for autotest is probably broken
 
-  s.files         = `git ls-files`.split("\n").uniq.sort.select{|f| !f.empty? }
+  s.files         = `git ls-files`.split("\n").uniq.sort.select { |f| !f.empty? }
   s.test_files    = `git ls-files spec test`.split("\n")
   s.executables   = []
   s.require_paths = ["lib"]

data/docraptor.yaml

@@ -1,8 +1,8 @@
 swagger: '2.0'
 
 info: # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#info-object
-  version: "1.3.0"
-  title: DocRaptor v1
+  version: "1.4.0"
+  title: DocRaptor
   description: "A native client library for the DocRaptor HTML to PDF/XLS service."
   termsOfService: "https://docraptor.com/tos"
   license:
@@ -55,14 +55,79 @@ paths:
           description: Unprocessable Entity
         500:
           description: Server Error
+
+  /hosted_docs:
+    post:
+      operationId: createHostedDoc
+      tags: [Doc]
+      description: >
+        Creates a hosted document synchronously.
+      security:
+        - basicAuth: []
+      parameters:
+        - name: doc
+          in: body
+          description: The document to be created.
+          required: true
+          schema:
+            $ref: '#/definitions/Doc'
+      responses:
+        200:
+          description: Successful response
+          schema:
+            $ref: '#/definitions/DocStatus'
+        400:
+          description: Bad Request
+        401:
+          description: Unauthorized
+        403:
+          description: Forbidden
+        422:
+          description: Unprocessable Entity
+        500:
+          description: Server Error
+
   /async_docs:
     post:
       operationId: createAsyncDoc
       tags: [Doc]
       description: >
         Creates a document asynchronously.
-        You must use a callback url or the the returned status id and the status api to find out when it completes.
-        Then use the download api to get the document.
+        You must use a callback url or the returned status id and the status API to find out when it completes.
+        Then use the download API to get the document.
+      security:
+        - basicAuth: []
+      parameters:
+        - name: doc
+          in: body
+          description: The document to be created.
+          required: true
+          schema:
+            $ref: '#/definitions/Doc'
+      responses:
+        200:
+          description: Successful response
+          schema:
+            $ref: '#/definitions/AsyncDoc'
+        400:
+          description: Bad Request
+        401:
+          description: Unauthorized
+        403:
+          description: Forbidden
+        422:
+          description: Unprocessable Entity
+        500:
+          description: Server Error
+
+  /hosted_async_docs:
+    post:
+      operationId: createHostedAsyncDoc
+      tags: [Doc]
+      description: >
+        Creates a hosted document asynchronously.
+        You must use a callback url or the returned status id and the status API to find out when it completes.
+        Then use the download API to get the document.
       security:
         - basicAuth: []
       parameters:
@@ -101,13 +166,12 @@ paths:
           in: path
           description: The status_id returned when creating an asynchronous document.
           required: true
-          schema:
-            $ref: '#/definitions/AsyncDocStatus'
+          type: string
       responses:
         200:
           description: Successful response
           schema:
-            $ref: '#/definitions/AsyncDocStatus'
+            $ref: '#/definitions/DocStatus'
         401:
           description: Unauthorized
         403:
@@ -120,14 +184,15 @@ paths:
       operationId: getAsyncDoc
       tags: [Doc]
       description: >
-        Downloads a document.
+        Downloads a finished document.
       security:
         - basicAuth: []
       parameters:
         - name: id
           in: path
-          description: The download_id returned from status request or a callback.
+          description: The download_id returned from an async status request or callback.
           required: true
+          type: string
       responses:
         200:
           description: Successful response
@@ -141,6 +206,30 @@ paths:
         500:
           description: Server Error
 
+  /expire/{id}:
+    patch:
+      operationId: expire
+      tags: [Doc]
+      description: >
+        Expires a previously created hosted doc.
+      security:
+        - basicAuth: []
+      parameters:
+        - name: id
+          in: path
+          description: The download_id returned from status request or hosted document response.
+          required: true
+          type: string
+      responses:
+        200:
+          description: Successful response
+        401:
+          description: Unauthorized
+        403:
+          description: Forbidden
+        500:
+          description: Server Error
+
 definitions:
   Doc:
     type: object
@@ -149,9 +238,6 @@ definitions:
       - document_type
       - document_content
     properties:
-      pipeline:
-        type: string
-        description: Specify a specific verison of the DocRaptor Pipeline to use.
       name:
         type: string
         description: A name for identifying your document.
@@ -176,13 +262,15 @@ definitions:
         type: boolean
         description: Enable test mode for this document. Test documents are not charged for but include a watermark.
         default: true
+      pipeline:
+        type: string
+        description: Specify a specific verison of the DocRaptor Pipeline to use.
       strict:
         type: string
         description: Force strict HTML validation.
-        default: none
         enum:
           - none
-          - true
+          - html
       ignore_resource_errors:
         type: boolean
         description: Failed loading of images/javascripts/stylesheets/etc. will not cause the rendering to stop.
@@ -209,8 +297,14 @@ definitions:
         type: string
         description: >
           A URL that will receive a POST request after successfully completing an asynchronous document.
-          The POST data will include download_url and download_id similar to status api responses.
+          The POST data will include download_url and download_id similar to status API responses.
           WARNING: this only works on asynchronous documents.
+      hosted_download_limit:
+        type: integer
+        description: The number of times a hosted document can be downloaded.  If no limit is specified, the document will be available for an unlimited number of downloads.
+      hosted_expires_at:
+        type: string
+        description: The date and time at which a hosted document will be removed and no longer available. Must be a properly formatted ISO 8601 datetime, like 1981-01-23T08:02:30-05:00.
       prince_options:
         $ref: '#/definitions/PrinceOptions'
 
@@ -340,9 +434,9 @@ definitions:
     properties:
       status_id:
         type: string
-        description: The identifier used to get the status of the document using the status api.
+        description: The identifier used to get the status of the document using the status API.
 
-  AsyncDocStatus:
+  DocStatus:
     type: object
     properties:
       status:
@@ -353,7 +447,7 @@ definitions:
         description: The URL where the document can be retrieved. This URL may only be used a few times.
       download_id:
         type: string
-        description: The identifier for downloading the document with the download api.
+        description: The identifier for downloading the document with the download API.
       message:
         type: string
         description: Additional information.

data/examples/hosted_async.rb

@@ -0,0 +1,75 @@
+# As a paid add-on, DocRaptor can provide long-term, publicly-accessible hosting for your documents.
+# This allows you to provide a URL to your end users, third party tools like Zapier and Salesforce,
+# or anyone else. We'll host the document on your behalf at a completely unbranded URL for as long
+# as you want, or within the limits you specify.
+#
+# This example demonstrates creating a PDF using common options that DocRaptor will host for you.
+# By default, hosted documents do not have limits on downloads or hosting time, though you may
+# pass additional parameters to the document generation call to set your own limits. Learn more
+# about the specific options in the hosted API documentation.
+# https://docraptor.com/documentation/api#api_hosted
+#
+# The document is created asynchronously, which means DocRaptor will allow it to generate for up to
+# 10 minutes. This is useful when creating many documents in parallel, or very large documents with
+# lots of assets.
+#
+# DocRaptor supports many options for output customization, the full list is
+# https://docraptor.com/documentation/api#api_general
+#
+# You can run this example with: ruby hosted_async.rb
+
+require "bundler/setup"
+Bundler.require
+require "open-uri"
+
+DocRaptor.configure do |dr|
+  dr.username  = "YOUR_API_KEY_HERE" # you will need a real api key to test hosted documents
+  # dr.debugging = true
+end
+
+$docraptor = DocRaptor::DocApi.new
+
+begin
+
+  # https://docraptor.com/documentation/api#api_general
+  create_response = $docraptor.create_hosted_async_doc(
+    test:             true,                                         # test documents are free but watermarked
+    document_content: "<html><body>Hello World</body></html>",      # supply content directly
+    # document_url:   "http://docraptor.com/examples/invoice.html", # or use a url
+    name:             "hosted-ruby-async.pdf",                      # helps you find a document later
+    document_type:    "pdf",                                        # pdf or xls or xlsx
+    # javascript:       true,                                       # enable JavaScript processing
+    # prince_options: {
+    #   media: "screen",                                            # use screen styles instead of print styles
+    #   baseurl: "http://hello.com",                                # pretend URL when using document_content
+    # },
+  )
+
+  loop do
+    status_response = $docraptor.get_async_doc_status(create_response.status_id)
+    puts "doc status: #{status_response.status}"
+    case status_response.status
+    when "completed"
+      puts "The hosted PDF is now available for public download at #{status_response.download_url}"
+      File.open("/tmp/docraptor-ruby.pdf", "wb") do |file|
+        open(status_response.download_url) do |uri|
+          file.write(uri.read)
+        end
+      end
+      puts "Wrote PDF to /tmp/docraptor-ruby.pdf"
+      break
+    when "failed"
+      puts "FAILED"
+      puts status_response
+      break
+    else
+      sleep 1
+    end
+  end
+
+rescue DocRaptor::ApiError => error
+  puts "#{error.class}: #{error.message}"
+  puts error.code          # HTTP response code
+  puts error.response_body # HTTP response body
+  puts error.backtrace[0..3].join("\n")
+end

data/examples/hosted_sync.rb

@@ -0,0 +1,62 @@
+# As a paid add-on, DocRaptor can provide long-term, publicly-accessible hosting for your documents.
+# This allows you to provide a URL to your end users, third party tools like Zapier and Salesforce,
+# or anyone else. We'll host the document on your behalf at a completely unbranded URL for as long
+# as you want, or within the limits you specify.
+#
+# This example demonstrates creating a PDF that DocRaptor will host for you using common options.
+# By default, hosted documents do not have limits on downloads or hosting time, though you may
+# pass additional parameters to the document generation call to set your own limits. Learn more
+# about the specific options in the hosted API documentation.
+# https://docraptor.com/documentation/api#api_hosted
+#
+# It is created synchronously, which means DocRaptor will allow it to generate for up to 60 seconds.
+# Since this document will be hosted by DocRaptor the response from this request will return a JSON
+# formatted object containing public URL where the document can be downloaded from.
+#
+# DocRaptor supports many options for output customization, the full list is
+# https://docraptor.com/documentation/api#api_general
+#
+# You can run this example with: ruby hosted_sync.rb
+
+require "bundler/setup"
+Bundler.require
+require "open-uri"
+
+DocRaptor.configure do |dr|
+  dr.username  = "YOUR_API_KEY_HERE" # you will need a real api key to test hosted documents
+  # dr.debugging = true
+end
+
+$docraptor = DocRaptor::DocApi.new
+
+begin
+
+  # https://docraptor.com/documentation/api#api_general
+  create_response = $docraptor.create_hosted_doc(
+    test:             true,                                         # test documents are free but watermarked
+    document_content: "<html><body>Hello World</body></html>",      # supply content directly
+    # document_url:   "http://docraptor.com/examples/invoice.html", # or use a url
+    name:             "docraptor-ruby.pdf",                         # help you find a document later
+    document_type:    "pdf",                                        # pdf or xls or xlsx
+    # javascript:       true,                                       # enable JavaScript processing
+    # prince_options: {
+    #   media: "screen",                                            # use screen styles instead of print styles
+    #   baseurl: "http://hello.com",                                # pretend URL when using document_content
+    # },
+  )
+  puts "The hosted PDF is now available for public download at #{create_response.download_url}"
+
+  File.open("/tmp/docraptor-ruby.pdf", "wb") do |file|
+    open(create_response.download_url) do |uri|
+      file.write(uri.read)
+    end
+  end
+
+  puts "Wrote PDF to /tmp/docraptor-ruby.pdf"
+
+rescue DocRaptor::ApiError => error
+  puts "#{error.class}: #{error.message}"
+  puts error.code          # HTTP response code
+  puts error.response_body # HTTP response body
+  puts error.backtrace[0..3].join("\n")
+end