docraptor 1.2.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: f1f969c08890cda4f67e62355949d52471fedb85
-  data.tar.gz: d1d683a98c87280aac9062a2dafbe2b3bdd0bbd3
+SHA256:
+  metadata.gz: bfd3d5b8d3364bd02c04b712136686d4a714f6cd3ab3fced0c7efae7e9709ee0
+  data.tar.gz: 89d4fb74883b56c49a71eef45487534474a8f9fa0ae8fc065a592e6a1ae7340c
 SHA512:
-  metadata.gz: 17fc69a5ff16512a9b62e1b1680bb9b37a5b7b4d4a3f50cf67ea7751db759f66b687d82a3be28a7803febc66f4371441b066cf0e1bd609d27f47e8ee41c9011c
-  data.tar.gz: f9f1e974ea8c64c83074be26200a94d3db6bc07318b59651d49e9500fa806b415f328534cd0376e09c48df1d7a74f2265166f01f50c095494886dcd77d1069b0
+  metadata.gz: 964a77fd28bb343dd5410b01e5b6981f631fd5c0ed047225b2dc048b8070249d9d704bb7a4bd289d154b406e8b794a2ac71e7d031af047bb8c47a0500c86b29d
+  data.tar.gz: 90787b9656e2455038833d260caf62b7aa48ce833d3de5e1483c1a9893feed6e0deb5d4cb995ee565510c0c3bfabe7e851decdf5cae00fd0389dc07d8319ff90

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.19

data/.swagger-revision

@@ -1 +1 @@
-v2.2.3
+v2.4.19

data/.travis.yml

@@ -0,0 +1,9 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.3.8
+  - 2.4.10
+  - 2.5.9
+  - 2.6.7
+  - 2.7.3
+  - 3.0.1

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+### 2.0.0 [June 1, 2021]
+* Add support for ruby 3.x (remove `URI.encode`)
+* Remove support for rubies <2.3
+
+### 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
+
 ### 1.2.0 [August 22, 2017]
 * No changes from beta1
 

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/README.md

@@ -18,9 +18,7 @@ bundle install
 ```
 
 
-## Usage
-
-See [examples](examples/) for runnable examples with file output, error handling, etc.
+## Basic Usage
 
 ```ruby
 DocRaptor.configure do |config|
@@ -44,20 +42,15 @@ response = $docraptor.create_doc(
 )
 ```
 
-Docs created like this are limited to 60 seconds to render, check out the [async example](examples/async.rb) which allows 10 minutes.
-
-We have guides for doing some of the common things:
-
-* [Headers and Footers](https://docraptor.com/documentation/style#pdf-headers-footers) including page skipping
-* [CSS Media Selector](https://docraptor.com/documentation/api#api_basic_pdf) to make the page look exactly as it does in your browser
-* Protect content with [HTTP authentication](https://docraptor.com/documentation/api#api_http_user) or [proxies](https://docraptor.com/documentation/api#api_http_proxy) so only DocRaptor can access them
+## Next Steps
 
+- Optionally store and get a URL for your converted document with [document hosting](https://docraptor.com/document-hosting)
+- View more [code examples](examples) with error handling, asynchronous creation, file saving, and document hosting.
+- Perfect your document styling with our [style and formatting reference](https://docraptor.com/documentation/style), and [API reference](https://docraptor.com/documentation/api). Easily add headers and footers, page breaks, page numbers, table of contents, and much more!
 
 ## More Help
 
-DocRaptor has a lot of more [styling](https://docraptor.com/documentation/style) and [implementation options](https://docraptor.com/documentation/api).
-
-Stuck? We're experts at using DocRaptor so please [email us](mailto:support@docraptor.com) if you run into trouble.
+Stuck? We're experts at turning HTML into PDFs so please [email us](mailto:support@docraptor.com) if you run into trouble.
 
 
 ## Development

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.0.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.19
 
 =end
 
@@ -24,11 +24,12 @@ 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.required_ruby_version = ">= 1.9"
+  s.license     = 'MIT'
+  s.required_ruby_version = ">= 2.3"
 
   s.add_runtime_dependency 'typhoeus', '~> 1.0', '>= 1.0.1'
   s.add_runtime_dependency 'json', '~> 2.1', '>= 2.1.0'
+  s.add_runtime_dependency 'addressable', '~> 2.3', '>= 2.3.0'
 
   s.add_development_dependency 'rspec', '~> 3.6', '>= 3.6.0'
   s.add_development_dependency 'vcr', '~> 3.0', '>= 3.0.1'
@@ -44,7 +45,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,7 +1,8 @@
 swagger: '2.0'
 
-info:
-  title: DocRaptor v1
+info: # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#info-object
+  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:
@@ -54,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:
@@ -100,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:
@@ -119,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
@@ -140,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
@@ -148,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.
@@ -175,17 +262,23 @@ 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.
         default: true
+      ignore_console_messages:
+        type: boolean
+        description: Prevent console.log from stopping document rendering during JavaScript execution.
+        default: false
       tag:
         type: string
         description: A field for storing a small amount of metadata with this document.
@@ -204,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'
 
@@ -300,7 +399,8 @@ definitions:
           - auto
       version:
         type: string
-        description: Specify a specific verison of PrinceXML to use.
+        deprecated: true
+        description: Deprecated, use the appropriate `pipeline` version. Specify a specific verison of PrinceXML to use.
         # default: 10
         # disabled because Java will try to make an enum as 7_1 which fails
         # enum:
@@ -321,17 +421,22 @@ definitions:
         # disabled because Java will try to make an enum with PDF/A-1b which fails
         # enum:
         #   - PDF/A-1b
+        #   - PDF/A-3b # (Pipeline 6+)
+        #   - PDF/X-1a # (Pipeline 6+)
         #   - PDF/X-3:2003
         #   - PDF/X-4
+      pdf_title:
+        type: string
+        description: Specify the PDF title, part of the document's metadata.
 
   AsyncDoc:
     type: object
     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:
@@ -342,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"
+  # 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"
+  # 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