uploadcare-ruby 2.1.1 → 3.1.0.pre.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: a91d6bc58cb4485cc93ff080fa5f66040b6ab0f0
-  data.tar.gz: ae95eb7e6d60828a91883c1c481e7a469d49702a
+SHA256:
+  metadata.gz: b37d6357bdceca37eb0175201e52847b253c701771e3bed959e7e945e4b384b7
+  data.tar.gz: c70b33bed6660c649df6e93a5bb7e8b3cb5a4c79884a7c146086f0658da690a3
 SHA512:
-  metadata.gz: e3b503ac19459939ec38af251f322c3804dec77546deeeba3d192757927a2cf4eef04d4f2b2ac2265efc42e42233f54d0f2fe66d2dcd29ced6ab18c65f6432c8
-  data.tar.gz: c08f3fb47d507b520c0859ee268ce8926b014fa7895b3a288f881586e857724a825f075899827f07a02c33228c790a26848728294cd5b8add0e323c14c49502f
+  metadata.gz: 47b8ead48824c45759a89a62e170374afe3cc0e8a39690ba4851c04785ee52096769a4415fea2e7ecffb62a864a5fae5f6fb1e95bf450442141973b0412990e7
+  data.tar.gz: a7aa262e0982825592487187f99018f5276582dffbfa3ef412abc06a3c9d723906d64d2443c79c20eb0dce137ae1cec4384c40b54e692170915289c8191032b0

data/.github/workflows/gem-push.yml

@@ -0,0 +1,20 @@
+name: Publish Gem
+
+on:
+  push:
+    tags:
+      - v*
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v1
+
+      - name: Release Gem
+        if: contains(github.ref, 'refs/tags/v')
+        uses: cadwallion/publish-rubygems-action@v1.0.0
+        env:
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+          RUBYGEMS_API_KEY: ${{secrets.RUBYGEMS_API_KEY}}
+          RELEASE_COMMAND: rake release

data/.github/workflows/ruby.yml

@@ -0,0 +1,52 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
+
+name: Ruby
+
+on: [push, pull_request]
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: [
+          '2.4', '2.5', # eol
+          '2.6', '2.7', # maintained
+        ]
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true
+    - name: Run tests
+      run: bundle exec rake
+      env:
+        UPLOADCARE_PUBLIC_KEY: demopublickey
+        UPLOADCARE_SECRET_KEY: demoprivatekey
+
+  style-check:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    strategy:
+      matrix:
+        ruby-version: ['2.7',]
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true
+    - name: Install Rubocop
+      run: gem install rubocop
+    - name: Check codestyle
+      run: rubocop

data/.gitignore

@@ -1,7 +1,14 @@
-Gemfile.lock
-.ruby-gemset
-.ruby-version
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/spec/fixtures/big.jpeg
 
-*.DS_Store
-*.gem
-coverage
+# rspec failure tracking
+.rspec_status
+.byebug_history
+Gemfile.lock

data/.rspec

@@ -1 +1,3 @@
+--format documentation
 --color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,32 @@
+AllCops:
+  TargetRubyVersion: 2.7
+
+Metrics/LineLength:
+  Max: 120
+
+IneffectiveAccessModifier:
+  Enabled: false
+
+Style/HashTransformKeys:
+  Exclude:
+    - 'lib/uploadcare/entity/decorator/paginator.rb'
+    - 'lib/uploadcare/client/conversion/video_conversion_client.rb'
+
+Gemspec/RequiredRubyVersion:
+  Exclude:
+    - 'uploadcare-ruby.gemspec'
+
+Metrics/BlockLength:
+  Exclude:
+    - 'bin/'
+    - 'spec/**/*'
+    - 'uploadcare-ruby.gemspec'
+
+Metrics/MethodLength:
+  Max: 20
+
+Style/Documentation:
+  Enabled: false
+
+Style/OptionalBooleanParameter:
+  AllowedMethods: ['create']

data/.yardopts

@@ -0,0 +1,4 @@
+-
+DEVELOPMENT.md
+CHANGELOG.md
+LICENSE

data/CHANGELOG.md

@@ -1,54 +1,53 @@
 # Changelog
-All notable changes to this project will be documented in this file.
 
-The format is based now on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
-and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+## 3.1.0-rc1 2021-08-11
 
-## [Unreleased] - FIXME
+### Added
+- Add video conversion
+- Add document conversion
+- Add new attributes to Uploadcare::File (variations, video_info, source, rekognition_info)
 
+### Fixed
 
-## [2.1.1] - 2018-05-24
+- Fix the `uninitialized constant Uploadcare::Client::ApiStruct (NameError)` error
 
-### Changed
-- Allow user to override User-Agent header
-- User-Agent format reports gem name, version and environment
+## 3.0.5 2021-04-15
 
-## 2.1.0 - 2018-04-23 [YANKED]
+- Replace Travis-CI with Github Actions
+- Automate gem pushing
 
-## 2.0.0 - 2017-09-26
+## 3.0.4-dev 2020-03-19
 
-There are **breaking** changes in this release, please read [upgrade notes](UPGRADE_NOTES.md#v1---v2)
+- Added better pagination methods for GroupList & FileList
+- Improved documentation and install instructions
+- Added CI
 
-### Added
-- Support for `store` flag in [Upload API](https://uploadcare.com/documentation/upload/) methods
-- Methods to store/delete multiple files at once: `Uploadcare::Api#store_files` & `Uploadcare::Api#delete_files`
+## 3.0.3-dev 2020-03-13
 
-### Changed
-- Upgraded to REST API v0.5
-- All POST/PUT/DELETE params are now being sent as JSON instead of being form-encoded
-- Pagination implementation for files and groups
+- Added better pagination and iterators for GroupList & FileList
 
-## 1.1.0 - 2017-03-21
+## 3.0.2-dev 2020-03-11
 
-### Added
-- Added to new methods to `Uploadcare::Api::File`, `#internal_copy` and `#external_copy`.
-- Added support of [secure authorization](https://uploadcare.com/documentation/rest/#request) for REST API. It is now used by default (can be overriden in config)
+- Expanded File and Group entities
+- Changed user agent syntax
 
-### Fixed
-- Fixed middleware names that could break other gems ([#13](https://github.com/uploadcare/uploadcare-ruby/issues/13)).
+## 3.0.1-dev 2020-03-11
 
-### Deprecated
-- `Uploadcare::Api::File#copy` in favor of `#internal_copy` and `#external_copy`.
+- Added Upload/group functionality
+- Added user API
+- Added user agent
+- Isolated clients, entities and concerns
+- Expanded documentation
 
+## 3.0.0-dev 2020-02-18
 
-## 1.0.6, 2017-01-30
+### Changed
+- Rewrote gem from scratch
 
 ### Added
-- Ruby version and public API key sent via User-Agent header (can be overriden in config)
-
-### Fixed
-- Incorrect dependencies
-
 
-[Unreleased]: https://github.com/uploadcare/uploadcare-ruby/compare/v2.1.1...HEAD
-[2.1.1]: https://github.com/uploadcare/uploadcare-ruby/compare/v2.0.0...v2.1.1
+- Client wrappers for REST API
+- Serializers for REST API
+- Client wrappers for Upload API
+- Serializers for Upload API
+- rdoc documentation

data/DEVELOPMENT.md

@@ -0,0 +1,18 @@
+## How to contribute
+
+https://github.com/uploadcare/.github/blob/master/CONTRIBUTING.md
+
+## Useful docs
+
+### Uploadcare:
+
+* https://uploadcare.com/docs/api_reference/
+* https://uploadcare.com/api-refs/rest-api/
+
+### ApiStruct:
+
+* https://github.com/rubygarage/api_struct/
+
+## Uploadcare-ruby gem architecture
+
+![http://www.plantuml.com/plantuml/uml/bPHDRzj838Rl-XM4zn1WiHRsOoyR88iuXOFcKWHDqcimaLxBquvcL9AowtxyzqepqYGrYY050cH69X-IByav5pMiVUkAed96X5QTfIy54T7jrWgDVrx16rE1De6fGKkzW2NQB9VB-7_zoRIT0zLmQ8oYfXQw3RMS9ZFgEnTCFLqsrk7UMT7YsnnsxTNguIZoNNIg38DMrrU4P2DWQvpz32wZzPtqnha3MStXXH9rIe8qq2jduPMSEO3_Y7x6rzJ0WwD3fjOK7jwZKg4DXvOOqWKlIB6klAZn5JBPS3v7UOQJ83j9-RnAASsNQHNlPsTdFv3iKJu9yJjT1gPBwp0ZHGCZdMDqHPP-LkPH-YGIjSQR1aACZpr4HnMFElApudwryMyXeUSAzDl5nSMGn0XIUB71HqLJrosacAj_4vHwGKtMqp_bd-LVongxH-0DU6ShJFMyCsn3BxI5wy1JQnDudS77LMJTfdfNjUaKFDnrb4Uc23KgMsDWXprfI7lICPHEKj4d4PBqe0SpfXmyTHnsjivZTZBDQlca8S5NO2zJ2Mlcm5GPhRPWYMEB-6ax71tusG8MY-Xu7praiI0sLY13dpceEYHuDBQRk6KCxTbBdc7QMzrI5MhGlt__bx4f-BqcZlNDm5Rp0K9cAZbcgcmH9uTxJrR9DCRw56-_XSSEF7vke4SvFSfnRTYqUJmXo5qqd5VDFhZfVKeRFIH4kwdthszlhwaRAL6gED2MCVJay8A1pfDyOnjlj6VCCGBBcEMgiuFFr__dD-mqx_VJ1sZ-DTPKf4joc_RlzBdNosC_sHLvOSe9ESFAUVIBYLWcwOeyJ-NCE8Ul-zPz1m00](http://www.plantuml.com/plantuml/svg/bPHDRzj838Rl-XM4zn1WiHRsOoyR88iuXOFcKWHDqcimaLxBquvcL9AowtxyzqepqYGrYY050cH69X-IByav5pMiVUkAed96X5QTfIy54T7jrWgDVrx16rE1De6fGKkzW2NQB9VB-7_zoRIT0zLmQ8oYfXQw3RMS9ZFgEnTCFLqsrk7UMT7YsnnsxTNguIZoNNIg38DMrrU4P2DWQvpz32wZzPtqnha3MStXXH9rIe8qq2jduPMSEO3_Y7x6rzJ0WwD3fjOK7jwZKg4DXvOOqWKlIB6klAZn5JBPS3v7UOQJ83j9-RnAASsNQHNlPsTdFv3iKJu9yJjT1gPBwp0ZHGCZdMDqHPP-LkPH-YGIjSQR1aACZpr4HnMFElApudwryMyXeUSAzDl5nSMGn0XIUB71HqLJrosacAj_4vHwGKtMqp_bd-LVongxH-0DU6ShJFMyCsn3BxI5wy1JQnDudS77LMJTfdfNjUaKFDnrb4Uc23KgMsDWXprfI7lICPHEKj4d4PBqe0SpfXmyTHnsjivZTZBDQlca8S5NO2zJ2Mlcm5GPhRPWYMEB-6ax71tusG8MY-Xu7praiI0sLY13dpceEYHuDBQRk6KCxTbBdc7QMzrI5MhGlt__bx4f-BqcZlNDm5Rp0K9cAZbcgcmH9uTxJrR9DCRw56-_XSSEF7vke4SvFSfnRTYqUJmXo5qqd5VDFhZfVKeRFIH4kwdthszlhwaRAL6gED2MCVJay8A1pfDyOnjlj6VCCGBBcEMgiuFFr__dD-mqx_VJ1sZ-DTPKf4joc_RlzBdNosC_sHLvOSe9ESFAUVIBYLWcwOeyJ-NCE8Ul-zPz1m00)

data/Gemfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 # Specify your gem's dependencies in uploadcare-ruby.gemspec

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2018 Uploadcare, LLC
+Copyright (c) 2021 Uploadcare Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,117 +1,92 @@
-[![Build Status][travis-img]][travis]
-[![Coverage Status][coverals-img]][coverals]
+# Ruby integration for Uploadcare
+
+![license](https://img.shields.io/badge/license-MIT-brightgreen.svg)
+[![Build Status][actions-img]][actions-badge]
 [![Uploadcare stack on StackShare][stack-img]][stack]
+<!--[![Coverage Status][coverals-img]][coverals]-->
 
-[travis-img]: https://secure.travis-ci.org/uploadcare/uploadcare-ruby.png?branch=master
-[travis]: http://travis-ci.org/uploadcare/uploadcare-ruby
-[coverals-img]: https://coveralls.io/repos/github/uploadcare/uploadcare-ruby/badge.svg?branch=master
-[coverals]: https://coveralls.io/github/uploadcare/uploadcare-ruby?branch=master
+[actions-badge]: https://github.com/uploadcare/uploadcare-ruby/actions/workflows/ruby.yml
+[actions-img]: https://github.com/uploadcare/uploadcare-ruby/actions/workflows/ruby.yml/badge.svg
+[coverals-img]: https://coveralls.io/repos/github/uploadcare/uploadcare-ruby/badge.svg?branch=main
+[coverals]: https://coveralls.io/github/uploadcare/uploadcare-ruby?branch=main
 [stack-img]: https://img.shields.io/badge/tech-stack-0690fa.svg?style=flat
 [stack]: https://stackshare.io/uploadcare/stacks/
 
-A [Ruby](https://www.ruby-lang.org/en/) wrapper for [Uploadcare](https://uploadcare.com).
+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
+* ruby 2.4+
+
+## Compatibility
+
+Note that `uploadcare-ruby` **3.x** is not backward compatible with
+**[2.x](https://github.com/uploadcare/uploadcare-ruby/tree/v2.x)**.
 
 ## Installation
 
-Installing `uploadcare-ruby` is quite simple and takes a couple of steps.
-First of, add the following line to your app's Gemfile:
+Add this line to your application's Gemfile:
 
 ```ruby
 gem 'uploadcare-ruby'
 ```
 
-Once you've added the line, execute this:
+And then execute:
 
-```shell
-$ bundle install
-```
+    $ bundle
 
-Or that (for manual install):
+If already not, create your project in [Uploadcare dashboard](https://uploadcare.com/dashboard/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-ruby) and copy
+its API keys from there.
 
-```shell
-$ gem install uploadcare-ruby
+Set your Uploadcare keys in config file or through environment variables:
+```bash
+export UPLOADCARE_PUBLIC_KEY=demopublickey
+export UPLOADCARE_SECRET_KEY=demoprivatekey
 ```
 
-## Initialization
-
-Init is simply done through creating an API object.
+Or configure your app yourself if you are using different way of storing keys.
+Gem configuration is available in `Uploadcare.configuration`. Full list of
+settings can be seen in [`lib/uploadcare.rb`](lib/uploadcare.rb)
 
 ```ruby
-require 'uploadcare'
-
-@api = Uploadcare::Api.new # default settings are used
-
-@api = Uploadcare::Api.new(settings) # using user-defined settings
+# your_config_initializer_file.rb
+Uploadcare.config.public_key = 'demopublickey'
+Uploadcare.config.secret_key = 'demoprivatekey'
 ```
 
-Here's how the default settings look like:
-
-``` ruby
-  {
-    public_key: 'demopublickey',   # you need to override this
-    private_key: 'demoprivatekey', # you need to override this
-    upload_url_base: 'https://upload.uploadcare.com',
-    api_url_base: 'https://api.uploadcare.com',
-    static_url_base: 'https://ucarecdn.com',
-    api_version: '0.5',
-    cache_files: true,
-    autostore: :auto,
-    auth_scheme: :secure
-  }
-```
-
-You're free to use both `demopublickey` and `demoprivatekey`
-for initial testing purposes. We wipe out files loaded to our
-demo account periodically. For a better experience,
-consider creating an Uploadcare account. Check out
-[this](http://kb.uploadcare.com/article/234-uc-project-and-account)
-article to get up an running in minutes.
-
-Please note, in order to use [Upload API](https://uploadcare.com/documentation/upload/)
-you will only need the public key alone. However, using
-[REST API](https://uploadcare.com/documentation/rest/) requires you to
-use both public and private keys for authentication.
-While “private key” is a common way to name a key from an
-authentication key pair, the actual thing for our `auth-param` is `secret_key`.
-
-`:autostore` option allows you to set the default storage
-behaviour upon uploads. For more info see [`store` flag][uploads from url] for
-uploads via URL and [`UPLOADCARE_STORE` flag][in-body file uploads] for file uploads 
-
-[in-body file uploads]: https://uploadcare.com/documentation/upload/#upload-body
-[uploads from url]: https://uploadcare.com/documentation/upload/#from-url
-
 ## Usage
 
-This section contains practical usage examples. Please note,
-everything that follows gets way more clear once you've looked
-through our docs [intro](https://uploadcare.com/documentation/).
+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).
 
-### Basic usage: uploading a single file, manipulations
+### Uploading files
+#### Uploading and storing a single file
 
 Using Uploadcare is simple, and here are the basics of handling files.
 
-First of, create the API object:
-
-```ruby
-@api = Uploadcare::Api.new(CONFIG)
-
-```
-
-And yeah, now you can upload a file:
-
 ```ruby
 @file_to_upload = File.open("your-file.png")
 
-@uc_file = @api.upload(@file_to_upload)
-# => #<Uploadcare::Api::File ...
-```
-
-Then, let's check out UUID and URL of the
-file you've just uploaded:
+@uc_file = Uploadcare::Uploader.upload(@file_to_upload)
 
-```ruby
-# file uuid (you'd probably want to store those somewhere)
 @uc_file.uuid
 # => "dc99200d-9bd6-4b43-bfa9-aa7bfaefca40"
 
@@ -120,10 +95,9 @@ file you've just uploaded:
 # => "https://ucarecdn.com/dc99200d-9bd6-4b43-bfa9-aa7bfaefca40/"
 ```
 
-Your might then want to store or delete the uploaded file.
-Storing files could be crucial if you aren't using the
-“Automatic file storing” option for your Uploadcare project.
-If not stored manually or automatically, files get deleted
+Your might then want to store or delete the uploaded file. Storing files could
+be crucial if you aren't using the “Automatic file storing” option for your
+Uploadcare project. If not stored manually or automatically, files get deleted
 within a 24-hour period.
 
 ```ruby
@@ -136,51 +110,28 @@ within a 24-hour period.
 # => #<Uploadcare::Api::File ...
 ```
 
-### Uploading a file from URL
+#### Multiple ways to upload files
 
-Now, this one is also quick. Just pass your URL into our API
-and you're good to go.
+Uploadcare supports multiple ways to upload files:
 
 ```ruby
-# the smart upload
-@file  = @api.upload "http://your.awesome/avatar.jpg"
-# =>  #<Uploadcare::Api::File ...
-
-# use this one if you want to explicitly upload from URL
-@file = @api.upload_from_url "http://your.awesome/avatar.jpg"
-# =>  #<Uploadcare::Api::File ...
+# Smart upload - detects type of passed object and picks appropriate upload method
+Uploadcare::Uploader.upload('https://placekitten.com/96/139')
 ```
-Keep in mind that providing invalid URL
-will raise `ArgumentError`.
-
-### Uploading multiple files
 
-Uploading multiple files is as simple as passing an array
-of `File` instances into our API.
+There are explicit ways to select upload type:
 
 ```ruby
-file1 = File.open("path/to/your/file.png")
-file2 = File.open("path/to/your/another-file.png")
-files = [file1, file2]
+files = [File.open('1.jpg'), File.open('1.jpg']
+Uploadcare::Uploader.upload_files(files)
 
-@uc_files = @api.upload files
-# => [#<Uploadcare::Api::File uuid="dc99200d-9bd6-4b43-bfa9-aa7bfaefca40">,
-#     #<Uploadcare::Api::File uuid="96cdc400-adc3-435b-9c94-04cd87633fbb">]
-```
-
-In case of multiple input, the respective output would also be an array.
-You can iterate through the array to address to single files.
-You might also want to request more info about a file using `load_data`.
+Uploadcare::Uploader.upload_from_url('https://placekitten.com/96/139')
 
-```ruby
-@uc_files[0]
-# => #<Uploadcare::Api::File uuid="dc99200d-9bd6-4b43-bfa9-aa7bfaefca40">
-
-@uc_files[1].load_data
-# => #<Uploadcare::Api::File uuid="96cdc400-adc3-435b-9c94-04cd87633fbb", original_file_url="https://ucarecdn.com/96cdc400-adc3-435b-9c94-04cd87633fbb/samuelzeller118195.jpg", image_info={"width"=>4896, "geo_location"=>nil, "datetime_original"=>nil, "height"=>3264}, ....>
+# multipart upload - can be useful for files bigger than 10 mb
+Uploadcare::Uploader.multipart_upload(File.open('big_file.bin'))
 ```
 
-### Upload options
+#### Uploading options
 
 You can override global [`:autostore`](#initialization) option for each upload request:
 
@@ -189,246 +140,89 @@ You can override global [`:autostore`](#initialization) option for each upload r
 @api.upload_from_url(url, store: :auto)
 ```
 
-### `File` object
-
-Now that we've already outlined using arrays of `File` instances
-to upload multiple files, let's fix on the `File` itself.
-It's the the primary object for Uploadcare API.
-Basically, it's an avatar for a file you uploaded.
-And all the further operations are performed using this avatar,
-the `File` object.
-
+### File management
+Most methods are also available through `Uploadcare::Api` object:
 ```ruby
-@file_to_upload = File.open("your-file.png")
-
-@uc_file = @api.upload(@file_to_upload)
-# => #<Uploadcare::Api::File ...
-
-@uc_file.uuid
-# => "dc99200d-9bd6-4b43-bfa9-aa7bfaefca40"
-
-@uc_file.cdn_url
-# => "https://ucarecdn.com/dc99200d-9bd6-4b43-bfa9-aa7bfaefca40/"
+# Same as Uploadcare::Uploader.upload
+Uploadcare::Api.upload('https://placekitten.com/96/139')
 ```
 
-Please note, all the data associated with files is only accessible
-through separate HTTP requests only. So if you don't specifically
-need file data (filenames, image dimensions, etc.), you'll be just
-fine with using `:uuid` and `:cdn_url` methods for file output:
+Entities are representations of objects in Uploadcare cloud.
 
-```erb
-<img src="#{@file.cdn_url}"/>
-```
-
-Great, we've just lowered a precious loading time.
-However, if you do need the data, you can always request
-it manually:
-
-```ruby
-@uc_file.load_data
-```
-
-That way your file object will respond to any method described
-in [API docs](https://uploadcare.com/documentation/rest/#file).
-Basically, that's an an OpenStruct, so you know what to do:
-
-```ruby
-@uc_file.original_filename
-# => "logo.png"
-
-@uc_file.image_info
-# => {"width"=>397, "geo_location"=>nil, "datetime_original"=>nil, "height"=>81}
-```
+#### File
 
-### `File` object from UUID or CDN URL
-
-`File` objects are needed to manipulate files on our CDN.
-The usual case would be you as a client storing file UUIDs
-or CDN URLs somewhere on your side, e.g. in a database.
-This is how you can use those to create `File` objects:
-
-```ruby
-# file object from UUID
-@file = @api.file "dc99200d-9bd6-4b43-bfa9-aa7bfaefca40"
-# => #<Uploadcare::Api::File uuid="dc99200d-9bd6-4b43-bfa9-aa7bfaefca40"
-
-# file object from CDN URL
-@file = @api.file "https://ucarecdn.com/dc99200d-9bd6-4b43-bfa9-aa7bfaefca40/"
-# => #<Uploadcare::Api::File uuid="dc99200d-9bd6-4b43-bfa9-aa7bfaefca40"
-
-# note, files you generate won't be loaded on init,
-# you'll need to load those manually
-@file.is_loaded?
-# => false
-```
-
-### Operations
-
-Another way to manipulate files on CDN is through operations.
-This is particularly useful for images.
-We've got on-the-fly crop, resize, rotation, format conversions, and
-[more](https://uploadcare.com/documentation/cdn/).
-Image operations are there to help you build responsive designs,
-generate thumbnails and galleries, change formats, etc.
-Currently, this gem has no specific methods for image operations,
-we're planning to implement those in further versions.
-However, we do support applying image operations through
-adding them to CDN URLs. That's an Uploadcare CDN-native
-way described in our [docs](https://uploadcare.com/documentation/cdn/).
+File entity contains its metadata.
 
 ```ruby
-@file = @api.file "https://ucarecdn.com/dc99200d-9bd6-4b43-bfa9-aa7bfaefca40/-/crop/150x150/center/-/format/png/"
-# => #<Uploadcare::Api::File uuid="dc99200d-9bd6-4b43-bfa9-aa7bfaefca40"
-
-@file.operations
-# => ["crop/150x150/center", "format/png"]
-
-# note that by default :cdn_url method returns URLs with no operations:
-@file.cdn_url
-# => "https://ucarecdn.com/dc99200d-9bd6-4b43-bfa9-aa7bfaefca40/""
-
-# you can pass "true" into the :cdn_url method to get URL including operations:
-@file.cdn_url(true)
-# => "https://ucarecdn.com/a8775cf7-0c2c-44fa-b071-4dd48637ecac/-/crop/150x150/center/-/format/png/"
-
-# there also are specific methods to either dump or include image operations
-# in the output URL:
-@file.cdn_url_with_operations
-@file.cdn_url_without_operations
-```
-
-While there's no operation wrapper, the best way of handling operations
-is through adding them to URLs as strings:
-
-```ruby
-<img src="#{file.cdn_url}-/crop/#{width}x#{height}/center/"/>
-# or something like that
-```
-
-### Copying files
-
-You can also create file copies using our API.
-There are multiple ways of creating those.
-Also, copying is important for image files because
-it allows you to “apply” all the CDN operations
-specified in the source URL to a separate static image.
-
-First of all, a copy of your file can be put in the Uploadcare storage.
-This is called “internal copy”, and here's how it works:
-
-```ruby
-@uc_file.internal_copy
-
-# =>
-{
-  "type"=>"file",
-  "result"=> {
-    "uuid"=>"a191a3df-2c43-4939-9590-784aa371ad6d",
-    "original_file_url"=>"https://ucarecdn.com/a191a3df-2c43-4939-9590-784aa371ad6d/19xldj.jpg",
-    "image_info"=>nil,
-    "datetime_stored"=>nil,
-    "mime_type"=>"application/octet-stream",
-    "is_ready"=>true,
-    "url"=>"https://api.uploadcare.com/files/a191a3df-2c43-4939-9590-784aa371ad6d/",
-    "original_filename"=>"19xldj.jpg",
-    "datetime_uploaded"=>"2017-02-10T14:14:18.690581Z",
-    "size"=>0,
-    "is_image"=>nil,
-    "datetime_removed"=>nil,
-    "source"=>"/4ea293d5-153f-422f-a24e-350237109606/"
-  }
-}
-```
-
-Once the procedure is complete, a copy would be a separate file
-with its own UUID and attributes.
-
-`#internal_copy` can optionally be used with the options hash argument.
-The available options are:
-
-- *store*
-
-  By default a copy is created without “storing”.
-  Which means it will be deleted within a 24-hour period.
-  You can make your output copy permanent by passing the
-  `store: true` option to the `#internal_copy` method.
-
-  Example:
-
-  ```ruby
-  @uc_file.internal_copy(store: true)
-  ```
-
-- *strip_operations*
+@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",
+ "image_info"=>
+  {"color_mode"=>"RGB",
+   "orientation"=>nil,
+   "format"=>"JPEG",
+   "sequence"=>false,
+   "height"=>183,
+   "width"=>190,
+   "geo_location"=>nil,
+   "datetime_original"=>nil,
+   "dpi"=>nil},
+ "is_image"=>true,
+ "is_ready"=>true,
+ "mime_type"=>"image/jpeg",
+ "original_file_url"=>
+  "https://ucarecdn.com/FILE_ID_IN_YOUR_PROJECT/imagepng.jpeg",
+ "original_filename"=>"image.png.jpeg",
+ "size"=>5345,
+ "url"=>
+  "https://api.uploadcare.com/files/FILE_ID_IN_YOUR_PROJECT/",
+ "uuid"=>"8f64f313-e6b1-4731-96c0-6751f1e7a50a"}
 
-  If your file is an image and you applied some operations to it,
-  then by default the same set of operations is also applied to a copy.
-  You can override this by passing `strip_operations: true` to the
-  `#internal_copy` method.
+@file.store # copies file, returns a new (copied) file metadata
 
-  Example:
+@file.store # stores file, returns updated metadata
 
-  ```ruby
-  file = @api.file "https://ucarecdn.com/24626d2f-3f23-4464-b190-37115ce7742a/-/resize/50x50/"
-  file.internal_copy
-  # => This will trigger POST /files/ with {"source": "https://ucarecdn.com/24626d2f-3f23-4464-b190-37115ce7742a/-/resize/50x50/"} in the body
-  file.internal_copy(strip_operations: true)
-  # => This will trigger POST /files/ with {"source": "https://ucarecdn.com/24626d2f-3f23-4464-b190-37115ce7742a/"} in the body
-  ```
-
-Another option is copying your file to a custom storage.
-We call it “external copy” and here's the usage example:
-
-```ruby
-@uc_file.external_copy('my_custom_storage_name')
-
-# =>
-{
-  "type"=>"url",
-  "result"=>"s3://my_bucket_name/c969be02-9925-4a7e-aa6d-b0730368791c/view.png"
-}
+@file.delete #deletes file. Returns updated metadata
 ```
 
-First argument of the `#external_copy` method is a name of
-a custom destination storage for your file.
-
-There's also an optional second argument — options hash. The available options are:
-
-  - *make_public*
-
-  Make a copy available via public links. Can be either `true` or `false`.
-
-  - *pattern*
+Metadata of deleted files is stored permanently.
 
-  Name pattern for a copy. If the parameter is omitted, custom storage pattern is used.
+#### FileList
 
-  - *strip_operations*
-
-  Same as for `#internal_copy`
-
-You might want to learn more about
-[storage options](https://uploadcare.com/documentation/storages/) or
-[copying files](https://uploadcare.com/documentation/rest/#files-post)
-with Uploadcare.
-
-
-### File lists
-
-`Uploadcare::Api::FileList` represents the whole collection of files (or it's subset) and privides a way to iterate through it, making pagination transparent. FileList objects can be created using `Uploadcare::Api#file_list` method.
+`Uploadcare::Entity::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.
 
 ```ruby
-@list = @api.file_list # => instance of Uploadcare::Api::FileList
+@list = Uploadcare::Entity.file_list
+# Returns instance of Uploadcare::Api::FileList
+<Hashie::Mash
+  next=nil
+  per_page=100
+  previous=nil
+  results=[
+    # Array of Entity::File
+  ]
+  total=8>
+# load last page of files
+@files = @list.files
+# load all files
+@all_files = @list.load
 ```
 
-This method accepts some options to controll which files should be fetched and how they should be fetched:
+This method accepts some options to controll which files should be fetched and
+how they should be fetched:
 
-- **:limit** - Controls page size. Accepts values from 1 to 1000, defaults to 100.
-- **:stored** - Can be either `true` or `false`. When true, file list will contain only stored files. When false - only not stored.
-- **:removed** - Can be either `true` or `false`. When true, file list will contain only removed files. When false - all except removed. Defaults to false.
-- **:ordering** - Controls the order of returned files. Available values: `datetime_updated`, `-datetime_updated`, `size`, `-size`. Defaults to `datetime_uploaded`. More info can be found [here](https://uploadcare.com/documentation/rest/#file-files)
-- **:from** - Specifies the starting point for a collection. Resulting collection will contain files from the given value and to the end in a direction set by an **ordering** option. When files are ordered by datetime_updated in any direction, accepts either a `DateTime` object or an ISO 8601 string. When files are ordered by size, acepts non-negative integers (size in bytes). More info can be found [here](https://uploadcare.com/documentation/rest/#file-files)
+- **:limit** — Controls page size. Accepts values from 1 to 1000, defaults to 100.
+- **:stored** — Can be either `true` or `false`. When true, file list will contain only stored files. When false — only not stored.
+- **:removed** — Can be either `true` or `false`. When true, file list will contain only removed files. When false — all except removed. Defaults to false.
+- **:ordering** — Controls the order of returned files. Available values: `datetime_updated`, `-datetime_updated`, `size`, `-size`. Defaults to `datetime_uploaded`. More info can be found [here](https://uploadcare.com/documentation/rest/#file-files/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-ruby).
+- **:from** — Specifies the starting point for a collection. Resulting collection will contain files from the given value and to the end in a direction set by an **ordering** option. When files are ordered by `datetime_updated` in any direction, accepts either a `DateTime` object or an ISO 8601 string. When files are ordered by size, accepts non-negative integers (size in bytes). More info can be found [here](https://uploadcare.com/documentation/rest/#file-files/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-ruby).
 
-Options used to create a file list can be accessed through `#options` method. Note that, once set, they don't affect file fetching process anymore and are stored just for your convenience. That is why they are frozen.
+Options used to create a file list can be accessed through `#options` method.
+Note that, once set, they don't affect file fetching process anymore and are
+stored just for your convenience. That is why they are frozen.
 
 ```ruby
 options = {
@@ -438,286 +232,315 @@ options = {
   from: "2017-01-01T00:00:00",
 }
 @list = @api.file_list(options)
-@list.options # => same as options hash above, but frozen
-```
-
-`Uploadcare::Api::FileList` implements Enumerable interface and holds a collection of `Uploadcare::Api::File` objects, as well as some meta information.
-
-```ruby
-@list = @api.file_list
-@list.total # => 1977
-@list.meta # => {
-#   "next"=> "https://api.uploadcare.com/files/?from=2017-03-09T10%3A30%3A01.877590%2B00%3A00&offset=0",
-#   "previous"=>nil,
-#   "total"=>1977,
-#   "per_page"=>100
-# }
-
-# Enumerable interface
-@list.first(5) # => array of 5 x Uploadcare::Api::File
-@list.each{|file| puts file.original_filename}
-@list.map{|file| file.uuid}
-@list.reduce(0){|overall_size, file| overall_size += file.size}
-# ...
 ```
 
-On the inside, `FileList` loada files page by page. First page is loaded when you call `Uploadcare::Api#file_list` and subsequent pages are being loaded when needed. The size of pages is controlled by a `:limit` option.
-
-Currently loaded files are available through `FileList#objects`. `FileList#loaded` method returns the number of currently loaded files.
-
+To simply get all associated objects:
 ```ruby
-@list = @api.file_list(limit: 5) # will load first 5 files
-@list.loaded # => 5
-@list.fully_loaded? # => false
-
-@list.objects # => array of 5 x Uploadcare::Api::File
-@list.objects[4] # => #<Uploadcare::Api::File ...>
-@list.objects[5] # => nil (since 6th file is not yet loaded)
-
-@list[4] # won't load anything, because 5 files are already loaded
-@list[5] # will load the next page
-@list.loaded # => 10
-
-# Note that the example below will load all the files left, page by page,
-# and return the count only when they all will be loaded
-@list.count # => 132
-@list.fully_loaded? # => true
+@list.all # => returns Array of Files
 ```
 
-Loaded files are preserved when `break` statement or an exception occures inside a block provided to #each, #map, etc.
+#### Pagination
 
+Initially, `FileList` is a paginated collection. It can be navigated using following methods:
 ```ruby
-@list = @api.file_list(limit: 10)
-@list.loaded # => 10
-
-i = 0
-@list.map do |file|
-  raise if i >= 19
-  i += 1
-  file.uuid
-end # => RuntimeError
-
-@list.loaded # => 20
+  @file_list = Uploadcare::Entity::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
 ```
 
-
-### Store / delete multiple files at once
-
-There are two methods to do so: `Uploadcare::Api#store_files` and
-`Uploadcare::Api#delete_files`. Both of them accept a list of either
-UUIDs or `Uploadcare::Api::File`s:
-
+Alternatively, it's possible to iterate through full list of groups or files with `each`:
 ```ruby
-uuids_to_store = ['f5c477e0-22af-469d-859a-712e14e14361', 'ec72c6eb-5ea8-4057-a009-52ffffb27c94']
-@api.store_files(uuids_to_store)
-# => {'status' => 'ok', 'problems' => {}, 'result' => [{...}, {...}]}
-
-old_files = @api.file_list(stored: true, ordering: '-datetime_uploaded', from: "2015-01-01T00:00:00")
-old_files.each_slice(100) do |batch|
-  response = @api.delete_files(batch)
-  # Do something with response if you need to
+@list.each do |file|
+  p file.url
 end
 ```
 
-Our API supports up to 100 files per request. Calling `#store_files` or
-`#delete_files` with more than 100 files at once will cause an ArgumentError.
+#### Group
 
-For more details see our [documentation on batch file storage/deletion](https://uploadcare.com/documentation/rest/#files-storage)
-
-### `Group` object
-
-Groups are structures intended to organize sets of separate files.
-Each group is assigned UUID.
-Note, group UUIDs include a `~#{files_count}` part at the end.
+Groups are structures intended to organize sets of separate files. Each group is
+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 = @api.upload @files_ary
-@group = @api.create_group @files
-# => #<Uploadcare::Api::Group uuid="0d192d66-c7a6-4465-b2cd-46716c5e3df3~2", files_count=2 ...
-
-# another way to from a group is via an array of strings holding UUIDs
-@uuids_ary = ["c969be02-9925-4a7e-aa6d-b0730368791c", "c969be02-9925-4a7e-aa6d-b0730368791c"]
-@group = @api.create_group @uuids_ary
-# => #<Uploadcare::Api::Group uuid="0d192d66-c7a6-4465-b2cd-46716c5e3df3~2", files_count=2 ...
+@files = Uploadcare::Uploader.upload @files_ary
+@group = Uploadcare::Group.create @files
 
-# also, you can create a group object via group UUID
-@group_uloaded = @api.group "#{uuid}"
+# 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)
 ```
 
-As with files, groups created via UUIDs are not loaded by default.
-You need to load the data manually, as it requires a separate
-HTTP GET request. New groups created with the `:create_group` method
-are loaded by default.
+#### GroupList
+`GroupList` is a list of `Group`
 
 ```ruby
-@group = @api.group "#{uuid}"
-
-@group.is_loaded?
-# => false
-
-@group.load_data
-# => #<Uploadcare::Api::Group uuid="0d192d66-c7a6-4465-b2cd-46716c5e3df3~2", files_count=2 ...
-
-# once a group is loaded, you can use any methods described in our API docs
-# the files within a loaded group are loaded by default
-@group.files
-# => [#<Uploadcare::Api::File uuid="24626d2f-3f23-4464-b190-37115ce7742a" ...>,
-#       ... #{files_count} of them ...
-#     #<Uploadcare::Api::File uuid="7bb9efa4-05c0-4f36-b0ef-11a4221867f6" ...>]
+@group_list = Uploadcare::GroupList.list
+# To get an array of groups:
+@groups = @group_list.all
 ```
 
-Check out our docs to learn more about
-[groups](https://uploadcare.com/documentation/rest/#group).
-
+This is a paginated list, so [pagination](#Pagination) methods apply
 
-### Group lists
+#### Webhook
+https://uploadcare.com/docs/api_reference/rest/webhooks/
 
-`Uploadcare::Api::GroupList` represents a group collection. It works in a same way as `Uploadcare::Api::FileList` does, but with groups.
+You can use webhooks to provide notifications about your uploads to target urls.
+This gem lets you create and manage webhooks.
 
 ```ruby
-@list = @api.group_list(limit: 10) # => instance of Uploadcare::Api::GroupList
-@list[0] # => instance of Uploadcare::Api::Group
+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
 ```
 
-The only thing that differs is an available options list:
-
-- **:limit** - Controls page size. Accepts values from 1 to 1000, defaults to 100.
-- **:ordering** - Controls the order of returned files. Available values: `datetime_created`, `-datetime_created`. Defaults to `datetime_created`. More info can be found [here](https://uploadcare.com/documentation/rest/#group-groups)
-- **:from** - Specifies the starting point for a collection. Resulting collection will contain files from the given value and to the end in a direction set by an **ordering** option. Accepts either a `DateTime` object or an ISO 8601 string. More info can be found [here](https://uploadcare.com/documentation/rest/#group-groups)
-
-
-### `Project` object
+#### Project
 
-`Project` provides basic info about the connected Uploadcare project.
-That object is also an OpenStruct, so every methods out of
-[these](https://uploadcare.com/documentation/rest/#project) will work.
+`Project` provides basic info about the connected Uploadcare project. That
+object is also an Hashie::Mash, so every methods out of
+[these](https://uploadcare.com/documentation/rest/#project/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-ruby) will work.
 
 ```ruby
-project = @api.project
+@project = Uploadcare::Project.project
 # => #<Uploadcare::Api::Project collaborators=[], name="demo", pub_key="demopublickey", autostore_enabled=true>
 
-project.name
+@project.name
 # => "demo"
 
-p.collaborators
+@project.collaborators
 # => []
 # while that one was empty, it usually goes like this:
 # [{"email": collaborator@gmail.com, "name": "Collaborator"}, {"email": collaborator@gmail.com, "name": "Collaborator"}]
 ```
 
-### Raw API
+#### Conversion
 
-Raw API is a simple interface allowing you to make
-custom requests to Uploadcare REST API.
-It's mainly used when you want a low-level control
-over your app.
+##### Video
 
-```ruby
-# here's how you make any requests
-@api.request :get, "/files/", {page: 2}
+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/).
 
-# and there also are shortcuts for methods
-@api.get '/files', {page: 2}
+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:
 
-@api.post ...
+```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:
 
-@api.put ...
+- **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
+```
 
-@api.delete ...
+- **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.
 
-All of the raw API methods return a parsed JSON response
-or raise an error (handling those is done on your side in the case).
+To convert multiple videos just add params as a hash for each video to the first argument of the `Uploadcare::VideoConverter#convert` method:
 
-### Error handling
+```ruby
+Uploadcare::VideoConverter.convert(
+  [
+    { video_one_params }, { video_two_params }, ...
+  ], store: false
+)
+```
 
-Starting from the version 1.0.2, we've got have custom exceptions
-that will be raised in case the Uploadcare service returns
-something with 4xx or 5xx HTTP status.
 
-Check out the list of custom errors:
+To check a status of a video processing job you can simply use appropriate method of `Uploadcare::VideoConverter`:
 
 ```ruby
-400 => Uploadcare::Error::RequestError::BadRequest,
-401 => Uploadcare::Error::RequestError::Unauthorized,
-403 => Uploadcare::Error::RequestError::Forbidden,
-404 => Uploadcare::Error::RequestError::NotFound,
-406 => Uploadcare::Error::RequestError::NotAcceptable,
-408 => Uploadcare::Error::RequestError::RequestTimeout,
-422 => Uploadcare::Error::RequestError::UnprocessableEntity,
-429 => Uploadcare::Error::RequestError::TooManyRequests,
-500 => Uploadcare::Error::ServerError::InternalServerError,
-502 => Uploadcare::Error::ServerError::BadGateway,
-503 => Uploadcare::Error::ServerError::ServiceUnavailable,
-504 => Uploadcare::Error::ServerError::GatewayTimeout
-```
-
-That's how you handle a particular error
-(in this case, a “404: Not Found” error):
+token = 911933811
+Uploadcare::VideoConverter.status(token)
+```
+`token` here is a processing job token, obtained in a response of a convert video request.
 
 ```ruby
-begin
-  @connection.send :get, '/random_url/', {}
-rescue Uploadcare::Error::RequestError::NotFound => e
-  nil
-end
+# Response
+{
+  :status => "finished",
+  :error => nil,
+  :result => {
+    :uuid => "dc99200d-9bd6-4b43-bfa9-aa7bfaefca40",
+    :thumbnails_group_uuid => "0f181f24-7551-42e5-bebc-14b15d9d3838~2"
+  }
+}
 ```
 
-Handling any request error (covers all 4xx status codes):
+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.
 
-```ruby
-begin
-  @connection.send :get, '/random_url/', {}
-rescue Uploadcare::Error::RequestError => e
-  nil
-end
-```
+More examples and options can be found [here](https://uploadcare.com/docs/transformations/video-encoding/#video-encoding)
+
+##### Document
 
-Handling any Uploadcare service error:
+Uploadcare allows converting documents to the following target formats: DOC, DOCX, XLS, XLSX, ODT, ODS, RTF, TXT, PDF, JPG, ENHANCED 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
-begin
-  @connection.send :get, '/random_url/', {}
-rescue Uploadcare::Error => e
-  nil
-end
+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
+)
 ```
 
-Since many of the above listed things depend on Uploadcare servers,
-errors might occasionally occur. Be prepared to handle those.
-
-## Testing
+This method accepts options to set properties of an output file:
 
-For testing purposes, run `bundle exec rspec`.
+- **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`, `enhanced.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.
 
-Please note, if you're willing to run tests using your own keys,
-make a `spec/config.yml` file containing the following:
+```
+  NOTE: Use an enhanced.jpg output format for PDF documents with inline fonts.
+        When converting multi-page documents to an image format (jpg or png), the output will be a zip archive with one image per page.
+```
 
-```yaml
-public_key: 'PUBLIC KEY'
-private_key: 'PRIVATE KEY'
+```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.
 
-## Contributors
+To convert multiple documents just add params as a hash for each document to the first argument of the `Uploadcare::DocumentConverter#convert` method:
 
-This is open source so fork, hack, request a pull — get a discount.
+```ruby
+Uploadcare::DocumentConverter.convert(
+  [
+    { doc_one_params }, { doc_two_params }, ...
+  ], store: false
+)
+```
 
-- [@romanonthego](https://github.com/romanonthego)
-- [@vizvamitra](https://github.com/vizvamitra)
-- [@dmitry-mukhin](https://github.com/dmitry-mukhin)
-- [@zenati](https://github.com/zenati)
-- [@renius](https://github.com/renius)
+To check a status of a document processing job you can simply use appropriate method of `Uploadcare::DocumentConverter`:
 
-## Security issues
+```ruby
+token = 21120220
+Uploadcare::DocumentConverter.status(token)
+```
+`token` here is a processing job token, obtained in a response of a convert document request.
 
-If you think you ran into something in Uploadcare libraries
-which might have security implications, please hit us up at
-[bugbounty@uploadcare.com](mailto:bugbounty@uploadcare.com)
-or Hackerone.
+```ruby
+# Response
+{
+  :status => "finished",
+  :error => nil,
+  :result => {
+    :uuid => "a4b9db2f-1591-4f4c-8f68-94018924525d"
+  }
+}
+```
 
-We'll contact you personally in a short time to fix an issue
-through co-op and prior to any public disclosure.
+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)
+* [Uploadcare documentation](https://uploadcare.com/docs/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-ruby)  
+* [Upload API reference](https://uploadcare.com/api-refs/upload-api/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-ruby)  
+* [REST API reference](https://uploadcare.com/api-refs/rest-api/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-ruby)  
+* [Changelog](./CHANGELOG.md)  
+* [Contributing guide](https://github.com/uploadcare/.github/blob/master/CONTRIBUTING.md)  
+* [Security policy](https://github.com/uploadcare/uploadcare-ruby/security/policy)  
+* [Support](https://github.com/uploadcare/.github/blob/master/SUPPORT.md)