pdf4me 2.0.3 → 2.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: daaba46ab2e5e8e3c811aa8a8be1e9bc9fded8c8
-  data.tar.gz: 7d2c3c51965f65072a16d53246fe1a1ed484680b
+  metadata.gz: a5cab03031af5c80c55ae0c20a0bd35ea2da1566
+  data.tar.gz: 39616938411754524c95e452ac15328cda1771e7
 SHA512:
-  metadata.gz: 5cfea5a92c49fef9fc6f971d0927ea992a347f882304e4afc040bb3bb6698f3eeb8b494f335524750cc409b694849d1144d46ed717fb7ff78df475a4147a3047
-  data.tar.gz: 32df2610543f47fa4d0cb28fe0f41e6ad9e7cda99e30974f3ea55e1eaf865e192e32b88a3327639a35380ba29731ae44d99e159248bb63bcd073312d78b65dda
+  metadata.gz: 7809803d64511e1abb269457fedfa97ba27b1774b0ac55970ac88408cc0b5d97d2697c90f79d7f2814521fec505ded8140489f4a0eae5622c051e949b10a1079
+  data.tar.gz: 871941878cfca1d14d6497053bcc1f7e34b2d8ff9f120ca9badac0622a3128bec2a1ee45646d314f27d1c404b1348e125cf6de46e79b2cc1908114d392e8eef4

data/README.md

@@ -157,7 +157,18 @@ a.run
 
 
 ## Advanced Usage
-> These methods are more complex than the Basic Wrapper methods. The development of which is still a Work in Progress. Currently there are two methods that you can use
+> These methods are more complex than the Basic Wrapper methods. The development of which is still a Work in Progress. Currently there are two methods that you can use.
+>
+> By default all the Advanced methods run in blocking mode -
+> i.e you wait for the server to send you the response.
+>
+> If you want to run the operation asynchronously - you will be notified by a webhook over the result -
+then please set `get_notification` to `true` in `Pdf4me::Notification`.
+>
+> When the `Pdf4me::Notification` object is set, it will overwrite what is the default behaviour
+defined on the application/api level.
+>
+>See Pdf4me-Developer page to configure the webhook on application level.
 
 ###convert_to_pdf
 
@@ -165,20 +176,28 @@ a.run
 `convert_file_to_pdf`. The request is instantiated as a hash with the `:req` key,
 that takes in `Pdf4me::ConvertToPdf` model.
 
-> The action takes three different models `:document`,  `:convertToPdfAction` and `:notification` and returns
+> The action takes three different models `:document`,  `:convert_to_pdf_action` and `:notification` and returns
 `Pdf4me::ConvertToPdfRes`
 
+> To get more information regarding the models, please refer the provided [model definition](https://pdf4medoc.blob.core.windows.net/doc/index.html?java#converttopdfreq)
+
 ```ruby
   file_path = '/path/to/file/TestDocToConvert.docx'
 
-  d = Pdf4me::ConvertToPdf.new(
+  action = Pdf4me::ConvertToPdf.new(
     document: Pdf4me::Document.new(
       doc_data: Base64.encode64(File.open(file_path, 'rb', &:read)),
       name: "TestDocToConvert.docx"
     ),
-    convert_to_pdf_action: Pdf4me::ConvertToPdfAction.new
+    convert_to_pdf_action: Pdf4me::ConvertToPdfAction.new,
+    notification: Pdf4me::Notification.new(get_notification: true) # async, set false to invoke blocking mode.
   )
-  response = d.run
+  response = action.run
+
+  # saving converted file
+  File.open('path/to/save.pdf', 'wb') do |f|
+    f.write(Base64.decode64(response.document.doc_data))
+  end
 ```
 
 ###optimize
@@ -187,23 +206,235 @@ that takes in `Pdf4me::ConvertToPdf` model.
 >
 > `:optimize` takes three different models `document`, `optimize_action` and `notification`
 >
-> `Pdf4me::OptimizeAction` takes multiple arguments, but most importantly `profile` is important
+> `Pdf4me::OptimizeAction` takes multiple arguments, important amongst them being `profile`
 >  * profile, valid values are `default`, `web`, `print`, `max`, `mRC`
 
+> The finer details on configuration can be found at the [model definition](https://pdf4medoc.blob.core.windows.net/doc/index.html?curl#optimizereq)
+
 ```ruby
-  file = '/path/to/file/4.pdf'
+    file_path = '/path/to/file/4.pdf'
+
+    action = Pdf4me::Optimize.new(
+        document: Pdf4me::Document.new(
+          doc_data: Base64.encode64(File.open(file_path, 'rb', &:read))
+        ),
+        optimize_action: Pdf4me::OptimizeAction.new(
+          use_profile: true,
+          profile: 'max'
+        )
+    )
+    response = action.run
 
-  Pdf4me::Optimize.new(
-    document: Pdf4me::Document.new(
-      doc_data: Base64.encode64(File.open(fi, 'rb', &:read))
-    ),
-    optimize_action: Pdf4me::OptimizeAction.new(
-      use_profile: true,
-      profile: 'max'
+    # saving optimized file
+    File.open('path/to/optimized.pdf', 'wb') do |f|
+      f.write(Base64.decode64(response.document.doc_data))
+    end
+```
+
+### extract
+>  Extract out pages from PDF. You can choose from the pages you want to get.
+
+> `extract` takes three model arguments
+> * `extract_action`
+> * `document`
+> * `notification` - non mandatory
+
+> To list all possible options for the models please refer the  [model definition](https://pdf4medoc.blob.core.windows.net/doc/index.html?curl#extractreq)
+
+```ruby
+    file_path = '/path/to/file/4.pdf'
+
+    action = Pdf4me::Extract.new(
+        document: Pdf4me::Document.new(
+          doc_data: Base64.encode64(File.open(file_path, 'rb', &:read))
+        ),
+        extract_action: Pdf4me::ExtractAction.new(
+          extract_pages: [1, 2, 5]
+        ),
+        notification: Pdf4me::Notification.new(get_notification: true) # async
     )
-  )
+    response = action.run
+
+    # saving extracted pages
+    File.open('path/to/extracted.pdf', 'wb') do |f|
+      f.write(Base64.decode64(response.document.doc_data))
+    end
+```
+
+### create_images
+> Creates images from the PDF Document. This is useful if you want to create thumbnails for the PDF.<br>
+> The options are highly configurable to get the desired output.
+> The output would be a base64 encoded object that you have to save.
+> `create_images` takes three different arguments.
+> * `document`
+> * `image_action`
+> * `notification` - non mandatory
+
+> Each model has their own set of attributes and hence can be configured further.
+The full documentation of model attributes are available at [model definition](https://pdf4medoc.blob.core.windows.net/doc/index.html?curl#createimagesreq)
+
+```ruby
+    file_path = '/path/to/file/4.pdf'
+
+    action = Pdf4me::CreateImages.new(
+        document: Pdf4me::Document.new(
+          doc_data: Base64.encode64(File.open(file_path, 'rb', &:read))
+        ),
+        image_action: Pdf4me::ImageAction.new(
+            page_selection: Pdf4me::PageSelection.new(
+              page_nrs: [1]
+            ),
+            image_extension: 'png',
+            center: true,
+            fit_page: true,
+            bits_per_pixel: 24,
+            bilevel_threshold: 181,
+            render_options: %w(noAntialiasing),
+            rotate_mode: 'none',
+            preserve_aspect_ratio: true,
+            compression: 'raw'
+       )
+    )
+    response = action.run
+
+    # saving the extracted thumbnail
+    File.open('thumbnail.png', 'wb') do |f|
+     f.write(Base64.decode64(response.document.pages.first.thumbnail))
+    end
 ```
 
+### merge
+> Merges two or more PDF and gives MergeRes, a Base64 Encoded file
+> `merge` takes three model arguments
+> * `documents` - An Array of `Pdf4me::Document`
+> * `merge_action` - `Pdf4me::MergeAction` model - non mandatory
+> * `notification` - `Pdf4me::Notification` model - non mandatory
+
+> To list all possible options for the models please refer the  [model definition](https://pdf4medoc.blob.core.windows.net/doc/index.html?curl#mergereq)
+
+```ruby
+
+    file_path_1 = '/path/to/file/4.pdf'
+    file_path_2 = '/path/to/file/3.pdf'
+    file_path_3 = '/path/to/file/2.pdf'
+
+    action = Pdf4me::Merge.new(
+        documents: [
+          Pdf4me::Document.new(
+            doc_data: Base64.encode64(File.open(file_path_1, 'rb', &:read))
+          ),
+          Pdf4me::Document.new(
+            doc_data: Base64.encode64(File.open(file_path_2, 'rb', &:read))
+          ),
+          Pdf4me::Document.new(
+            doc_data: Base64.encode64(File.open(file_path_3, 'rb', &:read))
+          )
+        ]
+    )
+    response = action.run
+
+    # saving the merged PDF
+    File.open('merged.pdf', 'wb') do |f|
+     f.write(Base64.decode64(response.document.doc_data))
+    end
+```
+
+### pdf_a
+> Creates PDF/A Documents from normal PDF document.
+> `pdf_a` takes three model arguments.
+> * `document` - a valid instance of `Pdf4me::Document`
+> * `pdf_a_action` - a valid instance of `Pdf4me::PdfAAction`
+> * `notification` - a valid instance of `Pdf4me::Notification` - non mandatory
+>
+> To list all possible options for the models please refer the  [model definition](https://pdf4medoc.blob.core.windows.net/doc/index.html?curl#createpdfareq)
+```ruby
+    file_path = '/path/to/file/4.pdf'
+
+    action = Pdf4me::PdfA.new(
+      document: Pdf4me::Document.new(
+        doc_data: Base64.encode64(File.open(file_path, 'rb', &:read))
+      ),
+      pdf_a_action: Pdf4me::PdfAAction.new(
+        compliance: 'pdfA1a',
+        allowDowngrade: true,
+        allowUpgrade: true,
+        outputIntentProfile: 'sRGBColorSpace',
+        linearize: true
+      )
+    )
+    response = action.run
+
+    # saving the PDF/A document
+    File.open('pdf_a.pdf', 'wb') do |f|
+     f.write(Base64.decode64(response.document.doc_data))
+    end
+```
+
+
+### split
+> Given a PDF, split the PDF into parts
+> `split` takes up three models
+> * `document` - a valid instance of `Pdf4me::Document`
+> * `split_action` - a valid instance of `Pdf4me::SplitAction` which defines the number of parts the PDF splits into
+> * `notification` - non mandatory, an instance of `Pdf4me::Notification`
+>
+> To list all possible options for the models please refer the  [model definition](https://pdf4medoc.blob.core.windows.net/doc/index.html?curl#splitreq)
+
+```ruby
+  file_path = '/path/to/file/4.pdf'
+
+   action = Pdf4me::Split.new(
+      document: Pdf4me::Document.new(
+        doc_data: Base64.encode64(File.open(file_path, 'rb', &:read)),
+      ),
+      split_action: Pdf4me::SplitAction.new(
+        split_after_page: 3
+      )
+    )
+  response = action.run
+
+  # save documents
+  response.documents.each_with_index do |document, index|
+    File.open("split_#{index}.pdf", 'wb') do |f|
+      f.write(Base64.decode64(document.doc_data))
+    end
+  end
+```
+
+# stamp
+> Stamp a PDF, based on Stamp Action.
+> You can stamp either a text or image to PDF, There are two separate methods defined to help you with stamping
+>  - Stamp PDF with image
+>  - Stamp PDF with Text
+> `stamp` takes three model arguments
+* `document` - a valid instance of `Pdf4me::Document`
+> * `stamp_action` - a valid instance of `Pdf4me::StampAction` which defines the stamp type, and position.
+> * `notification` - non mandatory, an instance of `Pdf4me::Notification`
+>
+> To list all possible options for the models please refer the  [model definition](https://pdf4medoc.blob.core.windows.net/doc/index.html?curl#stampreq)
+
+```ruby
+  file_path = '/path/to/file/4.pdf'
+
+   action = Pdf4me::Stamp.new(
+      document: Pdf4me::Document.new(
+        doc_data: Base64.encode64(File.open(file_path, 'rb', &:read)),
+      ),
+      stamp_action: Pdf4me::StampAction.new(
+        image: Pdf4me::Image.new(
+          image_data: Base64.encode64(File.open(image_path, 'rb', &:read))
+        )
+      )
+    )
+  response = action.run
+
+  # save stamped document
+  File.open('pdf_stamped.pdf', 'wb') do |f|
+    f.write(Base64.decode64(response.document.doc_data))
+   end
+```
+
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/pdf4me/pdf4me-clientapi-ruby.

data/lib/pdf4me.rb

@@ -28,6 +28,12 @@ require 'pdf4me/actions/text_stamp'
 require 'pdf4me/actions/complex_action'
 require 'pdf4me/actions/convert_to_pdf'
 require 'pdf4me/actions/optimize'
+require 'pdf4me/actions/create_images'
+require 'pdf4me/actions/extract'
+require 'pdf4me/actions/merge'
+require 'pdf4me/actions/pdf_a'
+require 'pdf4me/actions/split'
+require 'pdf4me/actions/stamp'
 
 # models
 require 'pdf4me/models/base'
@@ -40,6 +46,30 @@ require 'pdf4me/models/doc_metadata'
 require 'pdf4me/models/page'
 require 'pdf4me/models/optimize_action'
 require 'pdf4me/models/optimize_res'
+require 'pdf4me/models/color'
+require 'pdf4me/models/custom_cms_config'
+require 'pdf4me/models/extract_action'
+require 'pdf4me/models/extract_res'
+require 'pdf4me/models/image_action'
+require 'pdf4me/models/create_images_res'
+require 'pdf4me/models/merge_action'
+require 'pdf4me/models/merge_res'
+require 'pdf4me/models/page_selection'
+require 'pdf4me/models/pdf_a_action'
+require 'pdf4me/models/pdf_a_res'
+require 'pdf4me/models/pdf_font'
+require 'pdf4me/models/rgb_set'
+require 'pdf4me/models/rotate'
+require 'pdf4me/models/split_action'
+require 'pdf4me/models/split_res'
+require 'pdf4me/models/stamp_action'
+require 'pdf4me/models/stamp_res'
+require 'pdf4me/models/text'
+require 'pdf4me/models/transform'
+require 'pdf4me/models/translate'
+require 'pdf4me/models/image'
+
+
 
 module Pdf4me
   def self.configure

data/lib/pdf4me/actions/complex_action.rb

@@ -1,5 +1,6 @@
 module Pdf4me
   class ComplexAction
+    attr_accessor :notification
     attr_reader :client
 
     def client
@@ -37,6 +38,10 @@ module Pdf4me
       errors.flatten
     end
 
+    def notification
+      @notification || Pdf4me::Notification.new
+    end
+
     protected
 
     def attributes

data/lib/pdf4me/actions/convert_file_to_pdf.rb

@@ -14,7 +14,9 @@ module Pdf4me
     end
 
     def save_path
-      @save_path ||= File.join(File.dirname(file), "#{File.basename(file, ".*")}.pdf")
+      @save_path ||= unless file.nil?
+                       File.join(File.dirname(file), "#{File.basename(file, ".*")}.pdf")
+                     end
     end
 
     def call_api

data/lib/pdf4me/actions/convert_to_pdf.rb

@@ -1,14 +1,10 @@
 module Pdf4me
   class ConvertToPdf < ComplexAction
-    ATTRIBUTES = %w|document convert_to_pdf_action notification|
+    ATTRIBUTES = %w|document convert_to_pdf_action|
     attr_accessor *ATTRIBUTES
 
     def path
       '/Convert/ConvertToPdf'
     end
-
-    def notification
-      @notification || Pdf4me::Notification.new
-    end
   end
 end

data/lib/pdf4me/actions/create_images.rb

@@ -0,0 +1,10 @@
+module Pdf4me
+  class CreateImages < ComplexAction
+    ATTRIBUTES = %w|document image_action|
+    attr_accessor *ATTRIBUTES
+
+    def path
+      '/Image/CreateImages'
+    end
+  end
+end

data/lib/pdf4me/actions/create_thumbnail.rb

@@ -36,7 +36,9 @@ module Pdf4me
     end
 
     def save_path
-      @save_path ||= File.join(File.dirname(file), "#{File.basename(file, ".*")}-thumbnail.#{image_format}")
+      @save_path ||= unless file.nil?
+                       File.join(File.dirname(file), "#{File.basename(file, ".*")}-thumbnail.#{image_format}")
+                     end
     end
 
     def call_api

data/lib/pdf4me/actions/extract.rb

@@ -0,0 +1,10 @@
+module Pdf4me
+  class Extract < ComplexAction
+    ATTRIBUTES = %w|document extract_action|
+    attr_accessor *ATTRIBUTES
+
+    def path
+      '/Extract/Extract'
+    end
+  end
+end

data/lib/pdf4me/actions/extract_pages.rb

@@ -21,7 +21,9 @@ module Pdf4me
     end
 
     def save_path
-      @save_path ||= File.join(File.dirname(file), "extracted_pages.pdf")
+      @save_path ||= unless file.nil?
+                       File.join(File.dirname(file), "extracted_pages.pdf")
+                     end
     end
 
     def call_api
@@ -41,7 +43,7 @@ module Pdf4me
         errors.add(:pages, 'must be valid numeric value')
       end
 
-      unless pages.all? {|i| i.is_a?(Integer) }
+      unless pages.all? { |i| i.is_a?(Integer) }
         errors.add(:pages, 'contains values that are not numbers')
       end
     end