pcloud_api 0.2.3 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fcef0e50f4deec3483d2ce4f23882a453ed3cea1fac57ef507ee1523824aba33
-  data.tar.gz: 287a6037d5f81652a936d611a69cd2b40dd4ce5cdfbde03093242e0bcc7e061a
+  metadata.gz: 45e0e46ad9b58dd65f1ce2674c247fd72377fcb376bec9bdc29b3cb285216519
+  data.tar.gz: 25a81544a107633c7c3c4459a1ab0f3e7c1a4c6092d5231b59a22ccbce55bb9b
 SHA512:
-  metadata.gz: b9cc930698584cfebe1fbb501798cb15ccb8116e8d231f632c30813f37bc0912550cee1d3bcdfee66fd21add00e8d2874b8471173ca4c77b67a544b7efe2740a
-  data.tar.gz: ecdc92c74476eaed41515b5206d5c428f17fcddf870cd28f162fd382ba97abd11d095ef36ded8f155a188a36fe7a32afc4703df7275a779ec37628281de3da58
+  metadata.gz: dd0a131f94f7aec6ec700ad46ade522d37248d5475a23290d46b20f51025a5fd4043ccaf642fecdaeb387ef3cc85811282d0a52436dca6bdab1d8cbf23927211
+  data.tar.gz: 7597d199d6795c480d0b346ed021845993ad3f0bdd01fa9e6df1b129324c12c61dc181fa36f8990d85916016330d389413e6b6bdbeabb373c455e1ff4f3a1dfb

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## 0.2.3 2021-12-14
 
+**Changes**
+  1. You can now specify `recursive: true` on `Pcloud::Folder#find` and `Pcloud::Folder#find_by` methods to load all the folders contents recursively. Note that this may result in long request times for folders with many items in them.
+  2. You can now configure the pCloud API read and connect timeouts via a new `timeout_seconds` argument to `Pcloud::Client.configure()`. The previous way to set this value via a `PCLOUD_API_TIMEOUT_SECONDS` environment variable continues to work as before.
+
+## 0.2.3 2021-12-14
+
 **Changes**
   1. `Pcloud::File`'s `upload` method no longer requires a `:filename` param, since pCloud just reads it off of the file object and ignores the param anyway
   2. Both `Pcloud::File` and `Pcloud::Folder`'s `update` and `update!` methods now allow either partial paths _(starting and ending with slashes)_ or full paths. This is a little more dangerous if you specify a full path and you meant partial, but it's a reasonable use case to support.

data/README.md

@@ -4,7 +4,7 @@
 [![Gem Version](https://badge.fury.io/rb/pcloud_api.svg)](https://badge.fury.io/rb/pcloud_api)
 [![Gem Downloads](https://badgen.net/rubygems/dt/pcloud_api)](https://rubygems.org/gems/pcloud_api)
 
-The `pcloud_api` gem provides an intuitive Ruby interface for interacting with the [pCloud API](https://docs.pcloud.com/) using OAuth2. This gem does not attempt to replicate the entire functionality of the pCloud API but rather to provide quick and easy access for its most basic and common functionality. If you are looking for a lower-level pCloud API wrapper, [`pcloud`](https://github.com/7urkm3n/pcloud) might be a better fit for you.
+The `pcloud_api` gem provides an intuitive Ruby interface for interacting with the [pCloud API](https://docs.pcloud.com/) using OAuth2. This gem does not attempt to replicate the entire functionality of the pCloud API but rather to provide quick and easy access for its most important functionality. If you are looking for a lower-level pCloud API wrapper, [`pcloud`](https://github.com/7urkm3n/pcloud) might be a better fit for you.
 
 ## Installation
 
@@ -41,6 +41,7 @@ The `Pcloud::Client` can be configured by directly calling the `Pcloud::Client.c
 Pcloud::Client.configure(
   access_token: "your-pcloud-app-access-token",
   data_region: "EU"
+  timeout_seconds: 8 # optional integer, defaults to 8 seconds if not specified
 )
 ```
 
@@ -55,8 +56,12 @@ The `Pcloud::File` API includes:
 # Find files by file :id or :path:
 Pcloud::File.find(1)
 Pcloud::File.find_by(path: "/images/jack_the_cat.jpg")
-# NOTE: `find_by` can also be used with :id, though this will take precedence
-# over :path so just pick one or the other
+# NOTES:
+# - `find_by` can also be used with :id, though this will take precedence over
+#   :path so pick only one or the other
+# - Both `find` and `find_by` take an optional `recursive: true` argument which
+#   will recursively load all the folders contents. NOTE: this may result in
+#   long request times for folders with many items in them.
 
 # Check if a file exists by :id
 Pcloud::File.exists?(1)
@@ -106,8 +111,9 @@ The `Pcloud::Folder` API is very similar:
 # Find folders by folder :id or :path:
 Pcloud::Folder.find(1)
 Pcloud::Folder.find_by(path: "/images")
-# NOTE: `find_by` can also be used with :id, though this will take precedence
-# over :path so just pick one or the other
+# NOTES:
+# - `find_by` can also be used with :id, though this will take precedence over :path so pick only one or the other
+# - When using :path the folder object will have a `path` value, when finding by :id, `path` will be `nil`
 
 # Check if a folder exists by id
 Pcloud::Folder.exists?(1)
@@ -147,12 +153,12 @@ jack_images.parent_folder
 jack_images.contents
 ```
 
-**Aside: path vs id**
+**Params: path vs id**
 
-pCloud recommends using the `folder_id`, `parent_folder_id` or `file_id` params for API calls whenever possible, rather using an exact path. Folder and file ids are static, so this will make your code less brittle to changes in the file/folder tree. You can simply look up the id for a folder in the console ahead of time and then set it in your code, similar to how you would specify an AWS S3 bucket.
+pCloud recommends using the `folder_id`, `parent_folder_id` or `file_id` params for API calls whenever possible, rather than using an exact path. Folder and file ids are static, so this will make your code less brittle to changes in the file/folder tree. You can simply look up the id for a folder in the console ahead of time and then set it in your code, similar to how you would specify an AWS S3 bucket. Note that when finding by one of these id values, the `path` value of a folder will come back as `nil`.
 
 
-**Aside: off-label client use**
+**Off-label client use**
 
 The `Pcloud::File` and `Pcloud::Folder` APIs cover the most important, common functionality developers will want to access in a way that is easy to use without much onboarding. If you find that you still need to access other parts of the pCloud API that are not included in this gem yet, you can try calling other methods specified in [the pCloud API docs](https://docs.pcloud.com/) by interacting directly with the `Pcloud::Client`:
 ```ruby
@@ -160,6 +166,78 @@ Pcloud::Client.execute("listrevisions", query: { fileid: 90000 })
 ```
 _(There are a few methods on the raw pCloud API that require manual login, which this gem does not yet support. If you find that you need access to these methods you may wish to look at using the [`pcloud`](https://github.com/7urkm3n/pcloud) gem instead.)_
 
+### Example uses
+
+In addition to the API docs above, here are some real-world ideas of how you might use the `pcloud_api` gem in a project. Feel free to submit a PR if you have an example that you think others would benefit from as well!
+
+Upload a file from form params in Rails:
+```ruby
+Pcloud::File.upload(
+  path: "/Jack",
+  file: File.open(params[:file].path)
+)
+```
+
+Backup a database for a local script:
+```ruby
+Pcloud::File.upload(
+  folder_id: PCLOUD_FOLDER_ID,
+  filename: LOCAL_DB_FILENAME,
+  file: File.open("./#{LOCAL_DB_FILENAME}")
+)
+```
+
+Archive old state files and upload a new file for today:
+```ruby
+# NOTE: This will overwrite existing archive files for each day such that
+#       there is only ever one database file stored per day.
+Pcloud::Folder.find(PCLOUD_FOLDER_ID)
+  .contents
+  .filter { |item| item.is_a?(Pcloud::File) }
+  .filter { |file| file.name.match?(PCLOUD_STATE_FILE_REGEX) }
+  .each do |file|
+    file.update(
+      name: "#{file.created_at.strftime("%Y_%m_%d")}_#{file.name}",
+      parent_folder_id: PCLOUD_ARCHIVE_FOLDER_ID
+    )
+  end
+
+Pcloud::File.upload(
+  folder_id: PCLOUD_FOLDER_ID,
+  filename: LOCAL_DB_FILENAME,
+  file: File.open("./#{LOCAL_DB_FILENAME}")
+)
+```
+
+Safely download previous state files for a local script:
+```ruby
+Pcloud::Folder.find(PCLOUD_FOLDER_ID)
+  .contents
+  .filter { |item| item.is_a?(Pcloud::File) }
+  .filter { |file| file.name.match?(PCLOUD_STATE_FILE_REGEX) }
+  .each do |state_file|
+    filename = "./db/#{state_file.name}"
+    # prompt if local file is newer than cloud state file
+    if ::File.exist?(filename) && ::File.ctime(filename) > state_file.created_at
+      puts "Local #{filename} is newer than the version in pCloud. Are you sure you want to overwrite the local file with an older copy? [Y/N]".red
+      print "> ".red
+      unless ["yes", "y"].include?($stdin.gets.chomp.downcase)
+        puts "Skipping download of #{filename}...".yellow
+        next
+      end
+    end
+    # Only proceed with file download after confirmation or if cloud file is
+    # not older than local file.
+    ::File.open(filename, "w") do |file|
+      file.binmode
+      puts "Downloading #{filename} from pCloud...".yellow
+      HTTParty.get(state_file.download_url, stream_body: true) do |fragment|
+        file.write(fragment)
+      end
+    end
+  end
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/RELEASEING.md

@@ -3,5 +3,5 @@
 2. Make any documentation updates.
 3. Tag a new release in GitHub and summarize the changes since the last release.
 4. Build the gem locally: `gem build pcloud_api.gemspec`.
- * To test the gem in a local project, you can install it with `gem install --local pcloud_api-<VERSION>.gem`
+    * To test the gem in a local project, you can install it with `gem install --local pcloud_api-<VERSION>.gem`
 5. Publish the gem to rubygems.org: `gem push pcloud_api-<VERSION>.gem`.

data/lib/pcloud/client.rb

@@ -9,20 +9,21 @@ module Pcloud
     ].freeze
     US_API_BASE = "api.pcloud.com".freeze
     EU_API_BASE = "eapi.pcloud.com".freeze
-    TIMEOUT_SECONDS = ENV.fetch("PCLOUD_API_TIMEOUT_SECONDS", "8").to_i.freeze
+    DEFAULT_TIMEOUT_SECONDS = 8.freeze
 
     class << self
-      def configure(access_token: nil, data_region: nil)
+      def configure(access_token: nil, data_region: nil, timeout_seconds: nil)
         @@access_token = access_token
         @@data_region = data_region
+        @@timeout_seconds = timeout_seconds.nil? ? nil : timeout_seconds.to_i
         true # Don't accidentally return any secrets from the configure method
       end
 
       def execute(method, query: {}, body: {})
         verb = ["uploadfile"].include?(method) ? :post : :get
         options = {
-          headers: { "Authorization" => "Bearer #{access_token}" },
-          timeout: TIMEOUT_SECONDS # this sets both the open and read timeouts to the same value
+          headers: { "Authorization" => "Bearer #{access_token_from_config_or_env}" },
+          timeout: timeout_seconds_from_config_or_env # this sets both the open and read timeouts to the same value
         }
         options[:query] = query unless query.empty?
         options[:body] = body unless body.empty?
@@ -34,26 +35,32 @@ module Pcloud
 
       private
 
-      def data_region
+      def data_region_from_config_or_env
         @@data_region ||= ENV["PCLOUD_API_DATA_REGION"]
         return @@data_region if VALID_DATA_REGIONS.include?(@@data_region)
         raise ConfigurationError.new("Missing pCloud data region") if @@data_region.nil?
         raise ConfigurationError.new("Invalid pCloud data region, must be one of #{VALID_DATA_REGIONS}")
       end
 
-      def access_token
+      def access_token_from_config_or_env
         @@access_token ||= ENV["PCLOUD_API_ACCESS_TOKEN"]
         return @@access_token unless @@access_token.nil?
         raise ConfigurationError.new("Missing pCloud API access token")
       end
 
+      def timeout_seconds_from_config_or_env
+        @@timeout_seconds ||= ENV.fetch("PCLOUD_API_TIMEOUT_SECONDS", DEFAULT_TIMEOUT_SECONDS).to_i
+        return @@timeout_seconds unless @@timeout_seconds.zero?
+        raise ConfigurationError.new("Invalid pCloud API timeout seconds: cannot be set to 0")
+      end
+
       # You can manually hit "https://<default_server_for_your_region>/getapiserver"
       # to get some JSON which will tell you if there is a server in your region
       # closer to you than the default.
       def closest_server
         @@closest_server ||= begin
           return ENV["PCLOUD_API_BASE_URI"] if ENV["PCLOUD_API_BASE_URI"]
-          case data_region
+          case data_region_from_config_or_env
           when US_DATA_REGION
             US_API_BASE
           when EU_DATA_REGION

data/lib/pcloud/folder.rb

@@ -8,7 +8,7 @@ module Pcloud
     include Pcloud::TimeHelper
 
     SUPPORTED_UPDATE_PARAMS = [:name, :parent_folder_id, :path].freeze
-    SUPPORTED_FIND_BY_PARAMS = [:id, :path].freeze
+    SUPPORTED_FIND_BY_PARAMS = [:id, :path, :recursive].freeze
 
     attr_reader :id, :path, :name, :parent_folder_id, :is_deleted, :created_at,
                 :modified_at
@@ -91,8 +91,8 @@ module Pcloud
         raise e
       end
 
-      def find(id)
-        parse_one(Client.execute("listfolder", query: { folderid: id }))
+      def find(id, opts={})
+        parse_one(Client.execute("listfolder", query: { folderid: id, recursive: opts[:recursive] == true }))
       end
 
       def find_by(params)
@@ -100,7 +100,7 @@ module Pcloud
           raise InvalidParameters.new("Must be one of #{SUPPORTED_FIND_BY_PARAMS}")
         end
         raise InvalidParameters.new(":id takes precedent over :path, please only use one or the other") if params[:path] && params[:id]
-        query = { path: params[:path], folderid: params[:id] }.compact
+        query = { path: params[:path], folderid: params[:id], recursive: params[:recursive] == true }.compact
         parse_one(Client.execute("listfolder", query: query))
       end
     end

data/lib/pcloud/version.rb

@@ -1,3 +1,3 @@
 module Pcloud
-  VERSION = "0.2.3"
+  VERSION = "0.2.4"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pcloud_api
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.4
 platform: ruby
 authors:
 - Joshua Hunsche Jones
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-12-14 00:00:00.000000000 Z
+date: 2023-05-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -149,7 +149,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.22
+rubygems_version: 3.3.26
 signing_key:
 specification_version: 4
 summary: A Ruby library for interacting with the pCloud API