uploadcare-ruby 3.0.3 → 3.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4bdafd33b7c8ae9c4497155542a87b3b1797d72828d9be8649c74b731afefe10
-  data.tar.gz: e88de8ba3a43eb0ed7fa878d34831a11dadd7e1d103ea9781beed93bcd9b5eb9
+  metadata.gz: 50f31851c1ededcc13b14099d5451a2cae8ad1a1c36ce45bbe47447fc536dc3a
+  data.tar.gz: 0c5eecb5f2583645455230fb5679c65612e322a4dcae82cae97e5b9fc702dab4
 SHA512:
-  metadata.gz: f7adc9b72cf7587f09d6ffc1f3eea789d3c2c7ccb747b364b254a89783449aac38185a0cfcde5c7c89088eee658629804d606a1111d213e97433bc4727b31f2b
-  data.tar.gz: e88dc8694ac67b3eefba88218b111a5d51f8696e3dc9de9d3f46cf3bd7dbfadc53589ce2f94e43b78d1279758821edbe206c24a62df4088d126f76b90f200d94
+  metadata.gz: 0a1c5aef9d35b915e2a691ecaed88a1687bba7c7692e6c5066999e1348c5ba0bc9fe76e4afd3eea08da72b57f9a58379a7fc287385a316c6a12e795005e9b66e
+  data.tar.gz: 44a5eb8c106bd7b803428d4d8c7ad056b723dfc014baa4e94fd390c0924732a14b3d7ad9e262fa6e7de02a75bca073ee19b8476eda64c86b6fee1817380124c5

data/.rubocop.yml

@@ -7,6 +7,16 @@ Metrics/LineLength:
 IneffectiveAccessModifier:
   Enabled: false
 
+Style/HashTransformKeys:
+  Exclude:
+    - 'lib/uploadcare/entity/decorator/paginator.rb'
+    - 'lib/uploadcare/client/conversion/video_conversion_client.rb'
+    - 'lib/uploadcare/entity/file.rb'
+
+Gemspec/RequiredRubyVersion:
+  Exclude:
+    - 'uploadcare-ruby.gemspec'
+
 Metrics/BlockLength:
   Exclude:
     - 'bin/'
@@ -18,3 +28,6 @@ Metrics/MethodLength:
 
 Style/Documentation:
   Enabled: false
+
+Style/OptionalBooleanParameter:
+  AllowedMethods: ['create']

data/CHANGELOG.md

@@ -1,31 +1,45 @@
 # Changelog
 
-## [Unreleased](https://github.com/uploadcare/uploadcare-ruby/tree/develop)
+## 3.1.1 2021-10-13
 
-[Full Changelog](https://github.com/uploadcare/uploadcare-ruby/compare/0baded5593869f1d741f0fff22c58814970726b2...HEAD)
+- Fix Uploadcare::File#store
+- Fix Uploadcare::File#delete
 
-## [3.0.4-dev] 2020-03-19
+## 3.1.0 2021-09-21
+
+- Added documents and videos conversion
+- Added new attributes to the Entity class (variations, video_info, source, rekognition_info)
+- Added an opportunity to add custom logic to large files uploading process
+
+## 3.0.5 2021-04-15
+
+- Replace Travis-CI with Github Actions
+- Automate gem pushing
+
+## 3.0.4-dev 2020-03-19
 
 - Added better pagination methods for GroupList & FileList
 - Improved documentation and install instructions
 - Added CI
 
-## [3.0.3-dev] 2020-03-13
+## 3.0.3-dev 2020-03-13
 - Added better pagination and iterators for GroupList & FileList
 
-## [3.0.2-dev] 2020-03-11
+## 3.0.2-dev 2020-03-11
 
 - Expanded File and Group entities
 - Changed user agent syntax
 
-## [3.0.1-dev] 2020-03-11
+## 3.0.1-dev 2020-03-11
 
 - Added Upload/group functionality
 - Added user API
 - Added user agent
 - Isolated clients, entities and concerns
 - Expanded documentation
-## [3.0.0-dev] 2020-02-18
+
+## 3.0.0-dev 2020-02-18
+
 ### Changed
 - Rewrote gem from scratch
 

data/README.md

@@ -12,12 +12,24 @@
 [stack-img]: https://img.shields.io/badge/tech-stack-0690fa.svg?style=flat
 [stack]: https://stackshare.io/uploadcare/stacks/
 
-
 Uploadcare Ruby integration handles uploads and further operations with files by
 wrapping Upload and REST APIs.
 
 * [Installation](#installation)
 * [Usage](#usage)
+  * [Uploading files](#uploading-files)
+    * [Uploading and storing a single file](#uploading-and-storing-a-single-file)
+    * [Multiple ways to upload files](#multiple-ways-to-upload-files)
+    * [Uploading options](#uploading-options)
+  * [File management](#file-management)
+    * [File](#file)
+    * [FileList](#filelist)
+    * [Pagination](#pagination)
+    * [Group](#group)
+    * [GroupList](#grouplist)
+    * [Webhook](#webhook)
+    * [Project](#project)
+    * [Conversion](#conversion)
 * [Useful links](#useful-links)
 
 ## Requirements
@@ -25,7 +37,7 @@ wrapping Upload and REST APIs.
 
 ## Compatibility
 
-Note that `uploadcare-ruby` **3.x** is not backward compativble with 
+Note that `uploadcare-ruby` **3.x** is not backward compatible with
 **[2.x](https://github.com/uploadcare/uploadcare-ruby/tree/v2.x)**.
 
 ## Installation
@@ -33,7 +45,7 @@ Note that `uploadcare-ruby` **3.x** is not backward compativble with
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'uploadcare-ruby'
+gem "uploadcare-ruby"
 ```
 
 And then execute:
@@ -55,8 +67,8 @@ settings can be seen in [`lib/uploadcare.rb`](lib/uploadcare.rb)
 
 ```ruby
 # your_config_initializer_file.rb
-Uploadcare.config.public_key = 'demopublickey'
-Uploadcare.config.secret_key = 'demoprivatekey'
+Uploadcare.config.public_key = "demopublickey"
+Uploadcare.config.secret_key = "demoprivatekey"
 ```
 
 ## Usage
@@ -65,7 +77,8 @@ This section contains practical usage examples. Please note, everything that
 follows gets way more clear once you've looked through our
 [docs](https://uploadcare.com/docs/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-ruby).
 
-### Uploading and storing a single file
+### Uploading files
+#### Uploading and storing a single file
 
 Using Uploadcare is simple, and here are the basics of handling files.
 
@@ -78,7 +91,7 @@ Using Uploadcare is simple, and here are the basics of handling files.
 # => "dc99200d-9bd6-4b43-bfa9-aa7bfaefca40"
 
 # URL for the file, can be used with your website or app right away
-@uc_file.cdn_url
+@uc_file.url
 # => "https://ucarecdn.com/dc99200d-9bd6-4b43-bfa9-aa7bfaefca40/"
 ```
 
@@ -97,28 +110,71 @@ within a 24-hour period.
 # => #<Uploadcare::Api::File ...
 ```
 
-### Uploads
+#### Multiple ways to upload files
 
 Uploadcare supports multiple ways to upload files:
 
 ```ruby
 # Smart upload - detects type of passed object and picks appropriate upload method
-Uploadcare::Uploader.upload('https://placekitten.com/96/139')
+Uploadcare::Uploader.upload("https://placekitten.com/96/139")
 ```
 
 There are explicit ways to select upload type:
 
 ```ruby
-files = [File.open('1.jpg'), File.open('1.jpg']
+files = [File.open("1.jpg"), File.open("1.jpg"]
 Uploadcare::Uploader.upload_files(files)
 
-Uploadcare::Uploader.upload_from_url('https://placekitten.com/96/139')
+Uploadcare::Uploader.upload_from_url("https://placekitten.com/96/139")
+```
+It is possible to track progress of the upload-from-URL process. To do that, you should specify the `async` option and get a token:
+
+```ruby
+Uploadcare::Uploader.upload_from_url("https://placekitten.com/96/139", async: true)
+# => "c6e31082-6bdc-4cb3-bef5-14dd10574d72"
+```
+
+After the request for uploading-from-URL is sent, you can check the progress of the upload by sending the `get_upload_from_url_status` request:
 
+```ruby
+Uploadcare::Uploader.get_upload_from_url_status("1251ee66-3631-4416-a2fb-96ba59f5a515")
+# => Success({:size=>28511, :total=>28511, :done=>28511, :uuid=>"b829753b-6b64-4989-a167-ef15e4f3d190", :file_id=>"b859753b-zb64-4989-a167-ef15e4f3a190", :original_filename=>"video.ogg", :is_image=>false, :is_stored=>false, :image_info=>nil, :video_info=>nil, :is_ready=>true, :filename=>"video.ogg", :mime_type=>"audio/ogg", :status=>"success"})
+```
+
+In case of the `async` option is disabled, uploadcare-ruby tries to request the upload status several times (depending on the `max_request_tries` config param) and then returns uploaded file attributes.
+
+```ruby
 # multipart upload - can be useful for files bigger than 10 mb
-Uploadcare::Uploader.multipart_upload(File.open('big_file.bin'))
+Uploadcare::Uploader.multipart_upload(File.open("big_file.bin"), store: true)
 ```
 
-### Upload options
+For the multipart upload you can pass a block to add some additional logic after each file chunk is uploaded.
+For example to track file uploading progress you can do something like this:
+
+```ruby
+file = File.open("big_file.bin")
+progress = 0
+Uploadcare::Uploader.multipart_upload(file, store: true) do |options|
+  progress += (100.0 / options[:links_count])
+  puts "PROGRESS = #{progress}"
+end
+```
+Output of the code above looks like:
+```console
+PROGRESS = 4.545454545454546
+PROGRESS = 9.090909090909092
+PROGRESS = 13.636363636363637
+...
+```
+Options available in a block:
+- **:chunk_size** - size of each chunk in bytes;
+- **:object** - file object which is going to be uploaded;
+- **:offset** - offset from the beginning of a File object in bytes;
+- **:link_id** - index of a link provided by Uploadcare API. Might be treated as index of a chunk;
+- **:links** - array of links for uploading file's chunks;
+- **:links_count** - count of the array of links.
+
+#### Uploading options
 
 You can override global [`:autostore`](#initialization) option for each upload request:
 
@@ -127,14 +183,7 @@ You can override global [`:autostore`](#initialization) option for each upload r
 @api.upload_from_url(url, store: :auto)
 ```
 
-### Api
-Most methods are also available through `Uploadcare::Api` object:
-```ruby
-# Same as Uploadcare::Uploader.upload
-Uploadcare::Api.upload('https://placekitten.com/96/139')
-```
-
-### Entity object
+### File management
 
 Entities are representations of objects in Uploadcare cloud.
 
@@ -143,7 +192,7 @@ Entities are representations of objects in Uploadcare cloud.
 File entity contains its metadata.
 
 ```ruby
-@file = Uploadcare::File.file('FILE_ID_IN_YOUR_PROJECT')
+@file = Uploadcare::File.file("FILE_ID_IN_YOUR_PROJECT")
 {"datetime_removed"=>nil,
  "datetime_stored"=>"2020-01-16T15:03:15.315064Z",
  "datetime_uploaded"=>"2020-01-16T15:03:14.676902Z",
@@ -168,22 +217,64 @@ File entity contains its metadata.
   "https://api.uploadcare.com/files/FILE_ID_IN_YOUR_PROJECT/",
  "uuid"=>"8f64f313-e6b1-4731-96c0-6751f1e7a50a"}
 
+@file.copy # copies file, returns a new (copied) file metadata
+
 @file.store # stores file, returns updated metadata
 
 @file.delete #deletes file. Returns updated metadata
 ```
 
+The File object is also can be converted if it is a document or a video file. Imagine, you have a document file:
+
+```ruby
+@file = Uploadcare::File.file("FILE_ID_IN_YOUR_PROJECT")
+```
+
+To convert it to an another file, just do:
+
+```ruby
+@converted_file = @file.convert_document({ format: "png", page: "1" }, store: true)
+# => {
+#    "uuid"=>"<NEW_FILE_UUID>"}
+#    ...other file info...
+# }
+# OR
+# Failure({:"<FILE_UUID>/document/-/format/png/-/page/1/"=>"the target_format is not a supported 'to' format for this source file. <you_source_file_extension> -> png"})
+```
+
+Same works for video files:
+
+```ruby
+@converted_file = @file.convert_video(
+  {
+    format: "ogg",
+    quality: "best",
+    cut: { start_time: "0:0:0.1", length: "end" },
+    size: { resize_mode: "change_ratio", width: "600", height: "400" },
+    thumb: { N: 1, number: 2 }
+  },
+  store: true
+)
+# => {
+#    "uuid"=>"<NEW_FILE_UUID>"}
+#    ...other file info...
+# }
+# OR
+# Failure({:"<FILE_UUID>/video/-/size/600x400/preserve_ratio/-/quality/best/-/format/ogg/-/cut/0:0:0.1/end/-/thumbs~1/2/"=>"CDN Path error: Failed to parse remainder \"/preserve_ratio\" of \"size/600x400/preserve_ratio\""})
+```
+
+More about file conversion [here](#conversion).
 Metadata of deleted files is stored permanently.
 
 #### FileList
 
-`Uploadcare::Entity::FileList` represents the whole collection of files (or it's
+`Uploadcare::FileList` represents the whole collection of files (or it's
 subset) and provides a way to iterate through it, making pagination transparent.
-FileList objects can be created using `Uploadcare::Entity.file_list` method.
+FileList objects can be created using `Uploadcare::FileList.file_list` method.
 
 ```ruby
-@list = Uploadcare::Entity.file_list
-# Returns instance of Uploadcare::Api::FileList
+@list = Uploadcare::FileList.file_list
+# Returns instance of Uploadcare::Entity::FileList
 <Hashie::Mash
   next=nil
   per_page=100
@@ -198,7 +289,7 @@ FileList objects can be created using `Uploadcare::Entity.file_list` method.
 @all_files = @list.load
 ```
 
-This method accepts some options to controll which files should be fetched and
+This method accepts some options to control which files should be fetched and
 how they should be fetched:
 
 - **:limit** — Controls page size. Accepts values from 1 to 1000, defaults to 100.
@@ -215,7 +306,7 @@ stored just for your convenience. That is why they are frozen.
 options = {
   limit: 10,
   stored: true,
-  ordering: '-datetime_uploaded',
+  ordering: "-datetime_uploaded",
   from: "2017-01-01T00:00:00",
 }
 @list = @api.file_list(options)
@@ -226,15 +317,15 @@ To simply get all associated objects:
 @list.all # => returns Array of Files
 ```
 
-##### Pagination
+#### Pagination
 
 Initially, `FileList` is a paginated collection. It can be navigated using following methods:
 ```ruby
-  @file_list = Uploadcare::Entity::FileList.file_list
+  @file_list = Uploadcare::FileList.file_list
   # Let's assume there are 250 files in cloud. By default, UC loads 100 files. To get next 100 files, do:
   @next_page = @file_list.next_page
   # To get previous page:
-  @previous_page = @next_page.previous_page
+  @previous_page = @file_list.previous_page
 ```
 
 Alternatively, it's possible to iterate through full list of groups or files with `each`:
@@ -251,10 +342,14 @@ assigned UUID. Note, group UUIDs include a `~#{files_count}` part at the end.
 That's a requirement of our API.
 
 ```ruby
-# group can be created from an array of Uploadcare files
+# group can be created from an array of Uploadcare files (UUIDs)
+@file = "134dc30c-093e-4f48-a5b9-966fe9cb1d01"
+@file2 = "134dc30c-093e-4f48-a5b9-966fe9cb1d02"
 @files_ary = [@file, @file2]
-@files = Uploadcare::Uploader.upload @files_ary
 @group = Uploadcare::Group.create @files
+
+# group can be stored by group ID. It means that all files of a group will be stored on Uploadcare servers permanently
+Uploadcare::Group.store(group.id)
 ```
 
 #### GroupList
@@ -275,7 +370,10 @@ You can use webhooks to provide notifications about your uploads to target urls.
 This gem lets you create and manage webhooks.
 
 ```ruby
-Uploadcare::Webhook.create('example.com/listen', event: 'file.uploaded')
+Uploadcare::Webhook.create(target_url: "https://example.com/listen", event: "file.uploaded", is_active: true)
+Uploadcare::Webhook.update(<webhook_id>, target_url: "https://newexample.com/listen/new", event: "file.uploaded", is_active: true)
+Uploadcare::Webhook.delete("https://example.com/listen")
+Uploadcare::Webhook.list
 ```
 
 #### Project
@@ -297,6 +395,222 @@ object is also an Hashie::Mash, so every methods out of
 # [{"email": collaborator@gmail.com, "name": "Collaborator"}, {"email": collaborator@gmail.com, "name": "Collaborator"}]
 ```
 
+#### Conversion
+
+##### Video
+
+Uploadcare can encode video files from all popular formats, adjust their quality, format and dimensions, cut out a video fragment, and generate thumbnails via [REST API](https://uploadcare.com/api-refs/rest-api/v0.6.0/).
+
+After each video file upload you obtain a file identifier in UUID format.
+Then you can use this file identifier to convert your video in multiple ways:
+
+```ruby
+Uploadcare::VideoConverter.convert(
+  [
+    {
+      uuid: "dc99200d-9bd6-4b43-bfa9-aa7bfaefca40",
+      size: { resize_mode: "change_ratio", width: "600", height: "400" },
+      quality: "best",
+      format: "ogg",
+      cut: { start_time: "0:0:0.0", length: "0:0:1.0" },
+      thumbs: { N: 2, number: 1 }
+    }
+  ],
+  store: false
+)
+```
+This method accepts options to set properties of an output file:
+
+- **uuid** — the file UUID-identifier.
+- **size**:
+  - **resize_mode** - size operation to apply to a video file. Can be `preserve_ratio (default)`, `change_ratio`, `scale_crop` or `add_padding`.
+  - **width** - width for a converted video.
+  - **height** - height for a converted video.
+
+```
+  NOTE: you can choose to provide a single dimension (width OR height).
+        The value you specify for any of the dimensions should be a non-zero integer divisible by 4
+```
+
+- **quality** - sets the level of video quality that affects file sizes and hence loading times and volumes of generated traffic. Can be `normal (default)`, `better`, `best`, `lighter`, `lightest`.
+- **format** - format for a converted video. Can be `mp4 (default)`, `webm`, `ogg`.
+- **cut**:
+  - **start_time** - defines the starting point of a fragment to cut based on your input file timeline.
+  - **length** - defines the duration of that fragment.
+- **thumbs**:
+  - **N** - quantity of thumbnails for your video - non-zero integer ranging from 1 to 50; defaults to 1.
+  - **number** - zero-based index of a particular thumbnail in a created set, ranging from 1 to (N - 1).
+- **store** - a flag indicating if Uploadcare should store your transformed outputs.
+
+```ruby
+# Response
+{
+  :result => [
+    {
+      :original_source=>"dc99200d-9bd6-4b43-bfa9-aa7bfaefca40/video/-/size/600x400/change_ratio/-/quality/best/-/format/ogg/-/cut/0:0:0.0/0:0:1.0/-/thumbs~2/1/",
+      :token=>911933811,
+      :uuid=>"6f9b88bd-625c-4d60-bfde-145fa3813d95",
+      :thumbnails_group_uuid=>"cf34c5a1-8fcc-4db2-9ec5-62c389e84468~2"
+    }
+  ],
+  :problems=>{}
+}
+```
+Params in the response:
+- **result** - info related to your transformed output(-s):
+  - **original_source** - built path for a particular video with all the conversion operations and parameters.
+  - **token** - a processing job token that can be used to get a [job status](https://uploadcare.com/docs/transformations/video-encoding/#status) (see below).
+  - **uuid** - UUID of your processed video file.
+  - **thumbnails_group_uuid** - holds :uuid-thumb-group, a UUID of a [file group](https://uploadcare.com/api-refs/rest-api/v0.5.0/#operation/groupsList) with thumbnails for an output video, based on the thumbs [operation](https://uploadcare.com/docs/transformations/video-encoding/#operation-thumbs) parameters.
+- **problems** - problems related to your processing job, if any.
+
+To convert multiple videos just add params as a hash for each video to the first argument of the `Uploadcare::VideoConverter#convert` method:
+
+```ruby
+Uploadcare::VideoConverter.convert(
+  [
+    { video_one_params }, { video_two_params }, ...
+  ],
+  store: false
+)
+```
+
+
+To check a status of a video processing job you can simply use appropriate method of `Uploadcare::VideoConverter`:
+
+```ruby
+token = 911933811
+Uploadcare::VideoConverter.status(token)
+```
+`token` here is a processing job token, obtained in a response of a convert video request.
+
+```ruby
+# Response
+{
+  :status => "finished",
+  :error => nil,
+  :result => {
+    :uuid => "dc99200d-9bd6-4b43-bfa9-aa7bfaefca40",
+    :thumbnails_group_uuid => "0f181f24-7551-42e5-bebc-14b15d9d3838~2"
+  }
+}
+```
+
+Params in the response:
+- **status** - processing job status, can have one of the following values:
+  - *pending* — video file is being prepared for conversion.
+  - *processing* — video file processing is in progress.
+  - *finished* — the processing is finished.
+  - *failed* — we failed to process the video, see error for details.
+  - *canceled* — video processing was canceled.
+- **error** - holds a processing error if we failed to handle your video.
+- **result** - repeats the contents of your processing output.
+- **thumbnails_group_uuid** - holds :uuid-thumb-group, a UUID of a file group with thumbnails for an output video, based on the thumbs operation parameters.
+- **uuid** - a UUID of your processed video file.
+
+More examples and options can be found [here](https://uploadcare.com/docs/transformations/video-encoding/#video-encoding)
+
+##### Document
+
+Uploadcare allows converting documents to the following target formats: doc, docx, xls, xlsx, odt, ods, rtf, txt, pdf, jpg, png. Document Conversion works via our [REST API](https://uploadcare.com/api-refs/rest-api/v0.6.0/).
+
+After each document file upload you obtain a file identifier in UUID format.
+Then you can use this file identifier to convert your document to a new format:
+
+```ruby
+Uploadcare::DocumentConverter.convert(
+  [
+    {
+      uuid: "dc99200d-9bd6-4b43-bfa9-aa7bfaefca40",
+      format: "pdf"
+    }
+  ],
+  store: false
+)
+```
+or create an image of a particular page (if using image format):
+```ruby
+Uploadcare::DocumentConverter.convert(
+  [
+    {
+      uuid: "a4b9db2f-1591-4f4c-8f68-94018924525d",
+      format: "png",
+      page: 1
+    }
+  ],
+  store: false
+)
+```
+
+This method accepts options to set properties of an output file:
+
+- **uuid** — the file UUID-identifier.
+- **format** - defines the target format you want a source file converted to. The supported values are: `pdf` (default), `doc`, `docx`, `xls`, `xlsx`, `odt`, `ods`, `rtf`, `txt`, `jpg`, `png`. In case the format operation was not found, your input document will be converted to `pdf`.
+- **page** - a page number of a multi-paged document to either `jpg` or `png`. The method will not work for any other target formats.
+
+```ruby
+# Response
+{
+  :result => [
+    {
+      :original_source=>"a4b9db2f-1591-4f4c-8f68-94018924525d/document/-/format/png/-/page/1/",
+      :token=>21120220
+      :uuid=>"88fe5ada-90f1-422a-a233-3a0f3a7cf23c"
+    }
+  ],
+  :problems=>{}
+}
+```
+Params in the response:
+- **result** - info related to your transformed output(-s):
+  - **original_source** - source file identifier including a target format, if present.
+  - **token** - a processing job token that can be used to get a [job status](https://uploadcare.com/docs/transformations/document-conversion/#status) (see below).
+  - **uuid** - UUID of your processed document file.
+- **problems** - problems related to your processing job, if any.
+
+To convert multiple documents just add params as a hash for each document to the first argument of the `Uploadcare::DocumentConverter#convert` method:
+
+```ruby
+Uploadcare::DocumentConverter.convert(
+  [
+    { doc_one_params }, { doc_two_params }, ...
+  ],
+  store: false
+)
+```
+
+To check a status of a document processing job you can simply use appropriate method of `Uploadcare::DocumentConverter`:
+
+```ruby
+token = 21120220
+Uploadcare::DocumentConverter.status(token)
+```
+`token` here is a processing job token, obtained in a response of a convert document request.
+
+```ruby
+# Response
+{
+  :status => "finished",
+  :error => nil,
+  :result => {
+    :uuid => "a4b9db2f-1591-4f4c-8f68-94018924525d"
+  }
+}
+```
+
+Params in the response:
+- **status** - processing job status, can have one of the following values:
+  - *pending* — document file is being prepared for conversion.
+  - *processing* — document file processing is in progress.
+  - *finished* — the processing is finished.
+  - *failed* — we failed to process the document, see error for details.
+  - *canceled* — document processing was canceled.
+- **error** - holds a processing error if we failed to handle your document.
+- **result** - repeats the contents of your processing output.
+- **uuid** - a UUID of your processed document file.
+
+More examples and options can be found [here](https://uploadcare.com/docs/transformations/document-conversion/#document-conversion)
+
 ## Useful links
 
 * [Development](https://github.com/uploadcare/uploadcare-ruby/blob/main/DEVELOPMENT.md)

data/lib/uploadcare/client/conversion/base_conversion_client.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative '../rest_client'
+require 'exception/conversion_error'
+
+module Uploadcare
+  module Client
+    module Conversion
+      # This is a base client for conversion operations
+      #
+      # @see https://uploadcare.com/api-refs/rest-api/v0.6.0/#tag/Conversion
+      class BaseConversionClient < RestClient
+        API_VERSION_HEADER_VALUE = 'application/vnd.uploadcare-v0.5+json'
+
+        def headers
+          {
+            'Content-Type': 'application/json',
+            'Accept': API_VERSION_HEADER_VALUE,
+            'User-Agent': Uploadcare::Param::UserAgent.call
+          }
+        end
+
+        private
+
+        def send_convert_request(arr, options, url_builder_class)
+          body = build_body_for_many(arr, options, url_builder_class)
+          post(uri: convert_uri, content: body)
+        end
+
+        def success(response)
+          body = response.body.to_s
+          extract_result(body)
+        end
+
+        def extract_result(response_body)
+          return if response_body.empty?
+
+          parsed_body = JSON.parse(response_body, symbolize_names: true)
+          errors = parsed_body[:error] || parsed_body[:problems]
+          return Dry::Monads::Failure(errors) unless errors.nil? || errors.empty?
+
+          Dry::Monads::Success(parsed_body)
+        end
+
+        # Prepares body for convert_many method
+        def build_body_for_many(arr, options, url_builder_class)
+          {
+            paths: arr.map do |params|
+              url_builder_class.call(
+                **build_paths_body(params)
+              )
+            end,
+            store: options[:store]
+          }.compact.to_json
+        end
+      end
+    end
+  end
+end