pdf4me 1.0.1 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 431d852c1c429c6d2f4197af206dca26c866cbfd
-  data.tar.gz: 522eb046ccbece19c09f9f768734f26842df365d
+  metadata.gz: f4bac55f297137229d59ff76c455941c0c6038c5
+  data.tar.gz: b8e5adbb69464bcc0817b21bf41024e9d7a19562
 SHA512:
-  metadata.gz: f7ecb848b188c207e5f55efcaafd3e9a215a5da2e4eb5363db3778e082b2fc6248a6b59a4a28af3a3d8f115e452209f2628a4f6412d1378a7ce1b1bfee724000
-  data.tar.gz: d8bd4e8e19c5c44b4375f827a4dfcf46de25deff2137742bbf0330d5035704ad6d2e17e9bc15a1f85cdc71ddc4c708e956b68fc0c464772a42eb4341b2c64954
+  metadata.gz: f9d9e79554f8d23e335487d53b6040f0e06e3c702b9908c5a54a5d56efdbd6aab24cfcc1e40d99a4bb0df34897587d24447133b503cf970d0addda8a85810845
+  data.tar.gz: 8122fdc82c118e791eac26786866a3986450c6ac96b9046c49a14a9db56207793ee46b84e9050892217c17948345a17fd13296ea786e62bef287f8891384341a

data/{LICENSE → LICENSE.txt}

@@ -1,6 +1,6 @@
-MIT License
+The MIT License (MIT)
 
-Copyright (c) 2018 pdf4me
+Copyright (c) 2018 arpanlepcha
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -9,13 +9,13 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -4,39 +4,23 @@
 The tool provides utility over common PDF related task like `merge`, `create`, `stamp` and others, which can be
 found below.
 
-## Getting Started
+## Installation
 
 Add this line to your application's Gemfile:
 
-```shell
- gem 'pdf4me'
-```
-
-And then execute
-```shell
-bundle install
-# OR If you don't use bundler
-gem install pdf4me
+```ruby
+gem 'pdf4me'
 ```
 
-## Build locally/for development
-To build the Ruby code into a gem:
+And then execute:
 
-```shell
-gem build pdf4me.gemspec
-```
-
-Then either install the gem locally:
+    $ bundle
 
-```shell
-gem install ./pdf4me-1.0.0.gem
-```
+Or install it yourself as:
 
-## Install from Git
+    $ gem install pdf4me
 
-You can also install from a git repository: https://github.com/pdf4me/pdf4me-clientapi-ruby.git, then add the following in the Gemfile:
-
-    gem 'pdf4me', :git => 'https://github.com/pdf4me/pdf4me-clientapi-ruby.git'
+## Usage
 
 ## Initializing Pdf4me
 Pdf4me works with any Rack application or plain old ruby script. In any regular script the configuration of Pdf4me looks like
@@ -50,436 +34,181 @@ Pdf4me works with any Rack application or plain old ruby script. In any regular
     require 'pdf4me'
 
     Pdf4me.configure do |config|
-        config.host = 'api-dev.pdf4me.com'
-        config.debugging = true
-        config.app_id = 'your-app-id'
-        config.app_secret = 'your-app-secret'
+      config.host = 'api-dev.pdf4me.com'
+      config.token = 'valid-token'
     end
 ```
-
 ## Basic Usage
+> All basic methods exposes a safe and a dangerous method to execute the operation.
+> If the run fails, you can get the error through `.errors`
 
 ### convert_file_to_pdf
-> Given a file, convert the file to PDF
+> Given a file, convert the file to PDF. if `save_path` is not provided, the converted PDF is by defauled saved as file_name provided.
 
 ```ruby
-    api_instance = Pdf4me::ConvertApi.new
-    file = File.open(file_path, 'rb')
-    response = api_instance.convert_file_to_pdf(
-      file_name: 'some-name',
-      file: file
-    )
-    file.close
-```
-
-
-### convert_to_pdf
-> Given a file, convert the file to PDF, with finer controls as opposed to
-`convert_file_to_pdf`. The request is instantiated as a hash with the `:req` key,
-that takes in `Pdf4me::ConvertToPdf` model.
-
-> The model itself is comprised of three more models, `:document`,  `:convertToPdfAction`
- and `:notification`
-
-```ruby
-    api_instance = Pdf4me::ConvertApi.new
-    opts = {
-      req: Pdf4me::ConvertToPdf.new(
-        document: Pdf4me::Document.new(
-          docData: Base64.encode64(File.open(file_path, 'rb', &:read)),
-      ),
-      convertToPdfAction: Pdf4me::ConvertToPdfAction.new(
-        options: ""
-      ),
-      notification: Pdf4me::Notification.new(
-        getNotification: true
-      )
-    )
-  }
-  result = api_instance.convert_to_pdf(opts)
-```
+  b = Pdf4me::ConvertFileToPdf.new(
+        file: '/path/to/file/3.pdf',
+        save_path: 'converted.pdf'
+     )
+  b.run! # dangerous method
+  b.run # safe method - returns true|false
 
-### extract
->  Extract out pages from PDF. You can choose from the pages you want to extract
+  b.errors # to show errors
 
-```ruby
-    api_instance = Pdf4me::ExtractApi.new
-
-     opts = {
-      req: Pdf4me::Extract.new(
-            document: Pdf4me::Document.new(
-              docData: Base64.encode64(File.open(file_path, 'rb', &:read)),
-            ),
-            extractAction: Pdf4me::ExtractAction.new(
-              extractPages: Array.wrap(pages)
-            ),
-            notification: Pdf4me::Notification.new(
-              getNotification: true
-            )
-          )
-     }
-     api_instance.extract(opts)
 ```
 
-
 ### extract_pages
-> Utility function on top of extract, that trades complexity for configuration.
+> Extract particular set of pages from given PDF
 
 ```ruby
-    api_instance = Pdf4me::ExtractApi.new
-    response = File.open(file_path, 'rb') do |file|
-      api_instance.extract_pages(
-        page_nrs: '2,3,4',
-        file: file
-     )
-    end
-
-    # OR
-    file =  File.open(file_path, 'rb')
-    response = api_instance.extract_pages(
-      page_nrs: '2,3',
-      file: file
+    a = Pdf4me::ExtractPages.new(
+        file: '/path/to/file/3.pdf',
+        pages: [4],
+        save_path: 'extracted.pdf'
     )
-    file.close
-
-   # do something with response a tempfile
-   FileUtils.cp(response.path, '/new/file/path.pdf')
-```
-
-### create_images
-> Creates images from the PDF Document. This is useful if you want to create thumbnails for the PDF
-> The options are highly configurable to get the desired output.
-> The output would be a base64 encoded object that you have to save.
-
-```ruby
-    # initialize the API client
-    api_instance = Pdf4me::ImageApi.new
-
-    # make request hash
-    opts = {
-        req: Pdf4me::CreateImages.new(
-            document: Pdf4me::Document.new(
-              docData: Base64.encode64(File.open(file_path, 'rb', &:read)),
-            ),
-            imageAction: Pdf4me::ImageAction.new(
-              pageSelection: Pdf4me::PageSelection.new(
-                pageNrs: [1,2,3]
-              ),
-              imageExtension: 'png',
-              center: true,
-              fitPage: true,
-              bitsPerPixel: 24,
-              bilevelThreshold: 181,
-              renderOptions: %w(noAntialiasing),
-              rotateMode: 'none',
-              preserveAspectRatio: true,
-              compression: 'raw'
-            ),
-            notification: Pdf4me::Notification.new(
-              getNotification: true
-            )
-        )
-    }
-
-    # response and save
-    response = api_instance.create_images(opts)
-    File.open(save_path, 'wb') do |f|
-       f.write(Base64.decode64(response.document.doc_data))
-    end
+    a.run
 ```
 
 ### create_thumbnail
-> This is again a wrapper method on top of `:create_images`. The configuration is little less heckling
+> Create Thumbnail from existing PDF for a particular page number.
+> This takes in some additional configuration `width` defaulting to 100px, `image_format` defaulting to PNG
 
 ```ruby
-    api_instance = Pdf4me::ImageApi.new
-    file = File.open(file_path, 'rb')
-
-    response = api_instance.create_thumbnail(
-      100, # width in pixels
-      page_nr: "1", # for which page
-      image_format: "png", # image format
-      file: file
+    a = Pdf4me::CreateThumbnail.new(
+      file: '/path/to/file/3.pdf',
+      page_number: 4,
+      width: 120,
+      save_path: 'thumbnail.png'
     )
-
-    file.close
-
-    # do something with response a tempfile
-    FileUtils.cp(response.path, '/new/file/path.png')
-````
-
-### merge
-> Merges two or more PDF and gives MergeRes, a Base64 Encoded file
-
-```ruby
-    # Initialize the API client
-    api_instance = Pdf4me::MergeApi.new
-
-    # make request Hash
-    opts = {
-        req:  Pdf4me::Merge.new(
-            documents: [
-              Pdf4me::Document.new(
-                docData: Base64.encode64(File.open(file_path, 'rb', &:read)),
-              ),
-              Pdf4me::Document.new(
-                docData: Base64.encode64(File.open(file_path_2, 'rb', &:read)),
-             ),
-            ],
-            mergeAction: Pdf4me::MergeAction.new,
-            notification: Pdf4me::Notification.new
-        )
-    }
-
-    # make request
-    response = api_instance.merge(opts)
-    File.open(save_path, 'wb') do |f|
-      f.write(Base64.decode64(response.document.doc_data))
-    end
-````
+    a.run
+```
 
 ### merge2_pdfs
-> Utility method that merges two pdfs
+> Merges two PDFs, the order of merge is defined by the arguments passed.
+> * `file1` would always be the first followed by `file2` in merged PDF
 
 ```ruby
-    api_instance = Pdf4me::MergeApi.new
-
-    file1 = File.open(file_path, 'rb')
-    file2 = File.open(file_path_2, 'rb')
-
-    response = api_instance.merge2_pdfs(
-        file1: file1,
-        file2: file2
+    a = Pdf4me::MergeTwoPdfs.new(
+          file1: '/path/to/file/3.pdf',
+          file2: '/path/to/file/4.pdf',
+          save_path: 'merged.pdf'
     )
+    a.run
+```
 
-    file1.close
-    file2.close
+###optimize_by_profile
+> Optimizes a PDF based on th the profile argument passed.
+>  * valid values for profile are `default`, `web`, `print`, `max`, `mRC`
 
-    # do something with response a tempfile
-    FileUtils.cp(response.path, '/new/file/path.pdf')
+```ruby
+    a = Pdf4me::OptimizeByProfile.new(
+          file: '/path/to/file/3.pdf',
+          profile: 'max',
+          save_path: 'optimized.pdf'
+    )
+    a.run
 ```
 
-###optimize
 
-> Given a PDF document, Optimize the document.
-> `:optimize` takes multiple arguments, the arguments are
->
->  * profile, valid values are `default`, `web`, `print`, `max`, `mRC`
->  * dithering_mode, valid values are `none`, `floydSteinberg`, `halftone`, `pattern`, `g3Optimized`, `g4Optimized`, `atkinson`
-
-For complete list of options, please refer the `OptimizeAction` class
+### create_pdf_a
+> Creates a PDF/A Compliant document from a given PDF. By default it does not return any response.
+> * valid values for compliances are `unknown`, `pdf10`, `pdf11`, `pdf12`, `pdf13`, `pdf14`, `pdfA1b`, `pdfA1a`, `pdf15`, `pdf16`, `pdf17`, `pdfA2b`, `pdfA2u`, `pdfA2a`, `pdfA3b`, `pdfA3u`, `pdfA3a`
 
 ```ruby
-     # Initialize the API client
-    api_instance = Pdf4me::OptimizeApi.new
-
-    # prepare Request Hash
-    opts = {
-        req: Pdf4me::Optimize.new(
-            document: Pdf4me::Document.new(
-              docData: Base64.encode64(File.open(file_path, 'rb', &:read)),
-            ),
-            optimizeAction: Pdf4me::OptimizeAction.new(
-              profile: profile,
-              useProfile: true,
-              optimizeResources: true,
-              ditheringMode: dithering_mode
-            ),
-            notification: Pdf4me::Notification.new(
-              getNotification: true
-            )
-        )
-  }
-
-  # make request
-  response = api_instance.optimize(opts)
-  File.open(save_path, 'wb') do |f|
-    f.write(Base64.decode64(response.document.doc_data))
-  end
-
+   a = Pdf4me::CreatePdfA.new(
+        file: '/path/to/file/4.pdf',
+        compliance: 'pdfA1a',
+        save_path: 'to_pdfa.pdf'
+   )
+   a.run
 ```
 
-###optimize_by_profile
-> Utility function, that optimizes the PDF based on Profile as mentioned above
+### split_by_page_nr
+> Split a given PDF into two with page number as the pivot point.
 
 ```ruby
-    api_instance = Pdf4me::OptimizeApi.new
-    file = File.open(file_path, 'rb')
-
-    response = api_instance.optimize_by_profile(
-      'print',
-      file: file
-    )
-    file.close
-
-    # do something with response a tempfile
-   FileUtils.cp(response.path, '/new/file/path.pdf')
+    a = Pdf4me::SplitByPageNr.new(
+          file: '/path/to/file/3.pdf',
+          page_number: 3,
+          first_pdf: 'first.pdf', # defaults to '/path/to/file/3-first.pdf'
+          second_pdf: 'second.pdf' # defaults to '/path/to/file/3-second.pdf'
+   )
+    a.run
 ```
 
-### pdf_a
-> Creates PDF/A Documents. There are range of options that could be passed while creating the document. The options are
->   - `compliance` _string_ - Anyone of the following values `unknown`, `pdf10`, `pdf11`, `pdf12`, `pdf13`, `pdf14`, `pdfA1b`, `pdfA1a`, `pdf15`, `pdf16`, `pdf17`, `pdfA2b`, `pdfA2u`, `pdfA2a`, `pdfA3b`, `pdfA3u`, `pdfA3a`
->   - `downgrade` _boolean_ `true` or `false`
->   - `upgrade` _boolean_ `true` or `false`
->   - `linearize` _boolean_ `true` or `false`
+### text_stamp
+> Stamp a PDF with a text on particular sets of pages
+> Stamp takes additional arguments
+> * `position_x` - Position at X-Axis, valid values are `left`, `center`, `right`
+> * `position_y` - Position at Y-Axis, valid values are `top`, `middle`, `bottom`
+> * text - Text to stamp the PDF with and its mandatory.
 
 ```ruby
-    api_instance = Pdf4me::PdfAApi.new
-
-    opts = {
-        req: Pdf4me::CreatePdfA.new(
-            document: Pdf4me::Document.new(
-              docData: Base64.encode64(File.open(file_path, 'rb', &:read)),
-            ),
-            pdfAAction: Pdf4me::PdfAAction.new(
-              compliance: 'pdfA1a',
-              allowDowngrade: true,
-              allowUpgrade: true,
-              outputIntentProfile: 'sRGBColorSpace',
-              linearize: true
-            ),
-            notification: Pdf4me::Notification.new(
-              getNotification: true
-            )
-        )
-   }
-
-    # make request
-    response = api_instance.pdf_a(opts)
-    File.open('/path/to/save.pdf', 'wb') do |f|
-      f.write(Base64.decode64(response.document.doc_data))
-    end
+a = Pdf4me::TextStamp.new(
+      file: '/path/to/file/3.pdf',
+      pages: [1, 3],
+      position_x: 'left',
+      position_y: 'top',
+      text: 'Hell Pdf4me',
+      save_path: 'stamped.pdf'
+)
+a.run
 ```
 
-### create_pdf_a
-> Utility function based on above function
 
-```ruby
-    api_instance = Pdf4me::PdfAApi.new
-    file = File.open(file_path, 'rb')
+## 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
 
-    response = api_instance.create_pdf_a(
-      pdf_compliance: 'pdfA1a',
-      file: file
-    )
+###convert_to_pdf
 
-   file.close
-
-   # do something with response a tempfile
-   FileUtils.cp(response.path, '/new/file/path.pdf')
-```
+> Given a file, convert the file to PDF, with finer controls as opposed to
+`convert_file_to_pdf`. The request is instantiated as a hash with the `:req` key,
+that takes in `Pdf4me::ConvertToPdf` model.
 
-### split
-> Given a PDF, split the PDF into two parts
+> The action takes three different models `:document`,  `:convertToPdfAction` and `:notification` and returns
+`Pdf4me::ConvertToPdfRes`
 
 ```ruby
-    api_instance = Pdf4me::SplitApi.new
-
-    opts = {
-      req: Pdf4me::Split.new(
-        document: Pdf4me::Document.new(
-          docData: Base64.encode64(File.open(file_path, 'rb', &:read)),
-        ),
-        SplitAction: Pdf4me::SplitAction.new(
-          splitAfterPage: 3
-        ),
-        notificaiton: Pdf4me::Notification.new(
-          getNotification: true
-        )
-      )
-    }
-
-    response = api_instance.split(opts)
-
-    File.open(save_path, 'wb') do |f|
-        f.write(Base64.decode64(response.documents[0].doc_data))
-    end
+  file_path = '/path/to/file/TestDocToConvert.docx'
 
-    File.open(save_path_2, 'wb') do |f|
-      f.write(Base64.decode64(response.documents[0].doc_data))
-   end
+  d = 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
+  )
+  response = d.run
 ```
 
+###optimize
 
-### split_by_page_nr
-> Utility function to split the PDF by page number
+> Given a PDF document, Optimize the document and return `Pdf4me::OptimizeRes`
+>
+> `:optimize` takes three different models `document`, `optimize_action` and `notification`
+>
+> `Pdf4me::OptimizeAction` takes multiple arguments, but most importantly `profile` is important
+>  * profile, valid values are `default`, `web`, `print`, `max`, `mRC`
 
 ```ruby
-     api_instance = Pdf4me::SplitApi.new
-     file = File.open(file_path, 'rb')
-
-     response = api_instance.split_by_page_nr(
-      2, # page_number
-      file: file
-     )
+  file = '/path/to/file/4.pdf'
 
-     file.close
-
-     File.open(save_path, 'wb') do |f|
-      f.write(Base64.decode64(response.documents[0].doc_data))
-     end
-
-     File.open(save_path_2, 'wb') do |f|
-       f.write(Base64.decode64(response.documents[0].doc_data))
-     end
+  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'
+    )
+  )
 ```
 
-# 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
-> Depending upon the type of stamp, position, size can be configured.
+## Contributing
 
-```ruby
-    api_instance = Pdf4me::StampApi.new
-
-    opts = {
-      req: Pdf4me::Stamp.new(
-        document: Pdf4me::Document.new(
-          docData: Base64.encode64(File.open(file_path, 'rb', &:read)),
-        ),
-        stampAction: Pdf4me::StampAction.new(
-          image: Pdf4me::Image.new(
-            imageData: Base64.encode64(File.open(image, 'rb', &:read)),
-          ),
-          sizeX: stamp_width,
-          sizeY: stamp_length,
-          rotate: rotate,
-          alignX: align_x,
-          alignY: align_y,
-          scale: 'relToA4',
-          stampType: 'foreground',
-          alpha: opacity
-        ),
-        notification: Pdf4me::Notification.new(
-          getNotification: true
-        )
-      )
-    }
-
-    response = api_instance.stamp(opts)
-    File.open(save_path_2, 'wb') do |f|
-      f.write(Base64.decode64(response.document.doc_data))
-    end
-```
+Bug reports and pull requests are welcome on GitHub at https://github.com/pdf4me/pdf4me-clientapi-ruby.
 
-### text_stamp
-> Utility function over stamp, where you can stamp a document with text
+## License
 
-```ruby
-    api_instance = Pdf4me::StampApi.new
-    file = File.open(file_path, 'rb')
-
-    response = api_instance.text_stamp(
-      'right', # alignment x axis
-      'bottom', # alignment y axis,
-       text: 'Hello world, i am stamp',
-       pages: '1,4',
-       file: file
-    )
-    file.close
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
-    # do something with response a tempfile
-    FileUtils.cp(response.path, '/new/file/path.pdf')
-```