uploadcare-ruby 1.2.2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA256:
-  metadata.gz: 9363abb3c073881cc706fb59bc0b3d3b537a5db0fc53f4a186a726873bf622a6
-  data.tar.gz: ebdda4fafed6775f6904a9b4e1737241234d244ed42bed8c00a9fe1368d32027
+SHA1:
+  metadata.gz: 2951151a5b47adb4e4dab2c8b3dcd225aacd9f1c
+  data.tar.gz: 0c24efc39d8da2550ae26a3f129faf31326f1c6f
 SHA512:
-  metadata.gz: 9065fb7d524d457237d6ed507c405e4c83c8fb0de0f9a194dd259b35726353c6ea3dd96c23fd26f4a968784108cc6d8b2c6c593fb487345465e77c6b7960d9fb
-  data.tar.gz: f265a7b3fbcd3fcf716019edd99668b9b763463feaf46aeecc69accbe81bd5585b24ab6a31592fc8badac78c109228271ab95862ff811044beb4585d7c75e9c7
+  metadata.gz: b26a5b79dec7109fdb14c80fe9335d29aff594fa98942ce99e361936fba03a535a3b055667ac91cd49e7eb6068440634472f24ef5a9cc53608ba0195c2bae906
+  data.tar.gz: 65ee759c45a3122b551ff6fcdc237751a8b1252663d3cd360d54041e68fcc5a6a95d873c956ce351a4d24cd20634dcc9056e72da97f2e2831b4ade6a9abd6984

data/.gitignore

@@ -3,4 +3,4 @@ Gemfile.lock
 .ruby-version
 
 *.DS_Store
-*.gem
+*.gem

data/.rspec

@@ -0,0 +1 @@
+--color

data/.travis.yml

@@ -2,11 +2,25 @@ language: ruby
 
 rvm:
   - 1.9.3
-  - 2.0.0
-  - 2.1.10
-  - 2.2.6
-  - 2.3.3
-  - 2.4.0
+  - 2.0
+  - 2.1
+  - 2.2
+  - 2.3
+  - 2.4
+  - ruby-head
+
+jobs:
+  include:
+    - stage: style checks
+      rvm: 2.4
+      before_install:
+        - gem install rubocop
+      script:
+        - rubocop
+
+  allow_failures:
+    - stage: style checks
+    - rvm: ruby-head
 
 before_install:
   - gem update bundler

data/CHANGELOG.md

@@ -1,41 +1,23 @@
 # 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).
+### 2.0.0, 26.09.2017
 
-### [1.2.2] - 2018-06-11
+- There are **breaking** changes in this release, please read [upgrade notes](UPGRADE_NOTES.md#v1---v2)
+- Added support for `store` flag in [Upload API](https://uploadcare.com/documentation/upload/) methods
+- Upgraded to REST API v0.5
+- All POST/PUT/DELETE params are now being sent as JSON instead of being form-encoded
+- Added methods to store/delete multiple files at once: `Uploadcare::Api#store_files` & `Uploadcare::Api#delete_files`
+- Changed pagination implementation for files and groups
 
-### Fixed
-- Show Uploadcare::USER_AGENT deprecation warning only when the constant is being used
+### 1.1.0, 21.03.2017
 
-### [1.2.1] - 2018-05-24
-
-### Changed
-- Allow user to override User-Agent header
-- User-Agent format reports gem name, version and environment
-
-
-## 1.1.0 - 2017-03-21
-
-### Added
+- Deprecated `Uploadcare::Api::File#copy` in favor of `#internal_copy` and `#external_copy`.
 - 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)
-
-### Fixed
 - Fixed middleware names that could break other gems ([#13](https://github.com/uploadcare/uploadcare-ruby/issues/13)).
 
-### Deprecated
-- `Uploadcare::Api::File#copy` in favor of `#internal_copy` and `#external_copy`.
-
-
-## 1.0.6 - 2017-01-30
-
-### Added
-- Ruby version and public API key sent via User-Agent header (can be overriden in config)
-
-### Fixed
-- Incorrect dependencies
 
+### 1.0.6, 30.01.2017
 
-[1.2.1]: https://github.com/uploadcare/uploadcare-ruby/compare/6dde...v1.2.1
+- Fixed incorrect dependencies
+- Added ruby version and public API key to User-Agent header (can be overriden in config)

data/README.md

@@ -44,8 +44,9 @@ Here's how the default settings look like:
     upload_url_base: 'https://upload.uploadcare.com',
     api_url_base: 'https://api.uploadcare.com',
     static_url_base: 'https://ucarecdn.com',
-    api_version: '0.3',
+    api_version: '0.5',
     cache_files: true,
+    autostore: :auto,
     auth_scheme: :secure
   }
 ```
@@ -58,12 +59,19 @@ consider creating an Uploadcare account. Check out
 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 
+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.  
+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,
@@ -98,7 +106,7 @@ file you've just uploaded:
 @uc_file.uuid
 # => "dc99200d-9bd6-4b43-bfa9-aa7bfaefca40"
 
-# url for the file, can be used with your website or app right away
+# URL for the file, can be used with your website or app right away
 @uc_file.cdn_url
 # => "https://ucarecdn.com/dc99200d-9bd6-4b43-bfa9-aa7bfaefca40/"
 ```
@@ -126,11 +134,11 @@ and you're good to go.
 
 ```ruby
 # the smart upload
-@file  = @api.upload "http://your.awesome/avatar.jpg" 
+@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" 
+@file = @api.upload_from_url "http://your.awesome/avatar.jpg"
 # =>  #<Uploadcare::Api::File ...
 ```
 Keep in mind that providing invalid URL
@@ -163,6 +171,15 @@ You might also want to request more info about a file using `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}, ....>
 ```
 
+### Upload options
+
+You can override global [`:autostore`](#initialization) option for each upload request:
+
+```ruby
+@api.upload(files, store: true)
+@api.upload_from_url(url, store: :auto)
+```
+
 ### `File` object
 
 Now that we've already outlined using arrays of `File` instances
@@ -238,7 +255,7 @@ This is how you can use those to create `File` objects:
 
 ### Operations
 
-Another way to mainpulate files on CDN is through 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/).
@@ -356,7 +373,7 @@ 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"
@@ -383,7 +400,120 @@ There's also an optional second argument — options hash. The available options
 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. 
+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.
+
+```ruby
+@list = @api.file_list # => instance of Uploadcare::Api::FileList
+```
+
+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)
+
+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 = {
+  limit: 10,
+  stored: true,
+  ordering: '-datetime_uploaded',
+  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.
+
+```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
+```
+
+Loaded files are preserved when `break` statement or an exception occures inside a block provided to #each, #map, etc.
+
+```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
+```
+
+
+### 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:
+
+```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
+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.
+
+For more details see our [documentation on batch file storage/deletion](https://uploadcare.com/documentation/rest/#files-storage)
 
 ### `Group` object
 
@@ -433,75 +563,22 @@ are loaded by default.
 Check out our docs to learn more about
 [groups](https://uploadcare.com/documentation/rest/#group).
 
-### File lists and pagination
-
-File list is a paginated collection of files. Such lists are created
-to better represent the contents of your project.
-For this gem, a file list would be a single page containing
-20 files (you can override the number).
-There also are methods for navigating through pages.
-You can find more info about pagination
-[here](https://uploadcare.com/documentation/rest/#pagination).
-
-```ruby
-@list = @api.file_list 1 # page number, 1 is the default
-# => #<Uploadcare::Api::FileList ....
-
-
-# method :results returns an array of files
-@list.results
-# => [#<Uploadcare::Api::File uuid="24626d2f-3f23-4464-b190-37115ce7742a" ...>,
-#       ... 20 of them ...
-#     #<Uploadcare::Api::File uuid="7bb9efa4-05c0-4f36-b0ef-11a4221867f6" ...>]
-
 
-# note, every file is already loaded
-@list.results[1].is_loaded?
-# => true
+### Group lists
 
-
-# we've also added some shortcuts
-@list.to_a
-# => [#<Uploadcare::Api::File uuid="24626d2f-3f23-4464-b190-37115ce7742a" ...>,
-#       ... 20 of them ...
-#     #<Uploadcare::Api::File uuid="7bb9efa4-05c0-4f36-b0ef-11a4221867f6" ...>]
-
-@list[3]
-# => #<Uploadcare::Api::File ....
-```
-
-Here's how we handle navigating through pages:
+`Uploadcare::Api::GroupList` represents a group collection. It works in a same way as `Uploadcare::Api::FileList` does, but with groups.
 
 ```ruby
-@list = @api.files_list 3
-
-@list.next_page
-# => #<Uploadcare::Api::FileList page=4 ....
-
-@list.previous_page
-# => #<Uploadcare::Api::FileList page=2 ....
-
-@list.go_to 5
-# => #<Uploadcare::Api::FileList page=5 ....
-
-# of course, you can go with any of the methods
-# described in our API docs
-# total pages
-@list.pages
-# => 16
+@list = @api.group_list(limit: 10) # => instance of Uploadcare::Api::GroupList
+@list[0] # => instance of Uploadcare::Api::Group
+```
 
-# current page
-@list.page
-# => 3
+The only thing that differs is an available options list:
 
-# files per page
-@list.per_page
-# => 20
+- **: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)
 
-# total files in a project
-@list.total
-# => 308
-```
 
 ### `Project` object
 
@@ -581,7 +658,7 @@ rescue Uploadcare::Error::RequestError::NotFound => e
 end
 ```
 
-Handling any request error (covers all 4xx status codes): 
+Handling any request error (covers all 4xx status codes):
 
 ```ruby
 begin

data/Rakefile

@@ -1,5 +1,5 @@
 #!/usr/bin/env rake
-require "bundler/gem_tasks"
+require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 
 task :default => :spec

data/UPGRADE_NOTES.md

@@ -0,0 +1,36 @@
+# Upgrade notes
+
+## v1.* -> v2.*
+
+In 2.* release we've moved to [REST API v0.5][uploadcare-changelog-rest-api-v05] which introduces a new pagination for `/files/` and `/groups/` endpoints, so `Uploadcare::Api::FileList` and `Uploadcare::Api::GroupList` were completely reimplemented. 
+
+Previously, the file/group list API was:
+
+```ruby
+# creating
+list = api.file_list # => #<Uploadcare::Api::FileList page=1 ...>
+
+# accessing files/groups
+list.results # => [#<Uploadcare::Api::File>, ...]
+
+# pagination
+list.next_page # => #<Uploadcare::Api::FileList page=2 ...>
+list.previous_page # => #<Uploadcare::Api::FileList page=1 ...>
+list.go_to 5 # => #<Uploadcare::Api::FileList page=5 ...>
+
+# metadata
+list.pages # => 15
+list.page # => 5
+list.total # => 308 (files in a project)
+```
+
+It **won't work anymore**. For the details on the new file/group lists interface see [readme][readme]
+
+The core features of the new file/group list API are: 
+
+- transparent pagination via enumerable interface
+- loading objects on demand
+- ordering, filtering and slicing
+
+[uploadcare-changelog-rest-api-v05]: https://uploadcare.com/changelog/tag/rest-api#rest-api-version-05
+[readme]: https://github.com/uploadcare/uploadcare-ruby#file-lists