pcloud_api 0.2.2 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9fc8c976ed07fce0322907df07ed86d464b5924e6fb465aaa2bc5154b5fe95e8
-  data.tar.gz: e86aaee5ef4453da35281d3d3840078dfc639552c8913de6f4389a571e862256
+  metadata.gz: 45e0e46ad9b58dd65f1ce2674c247fd72377fcb376bec9bdc29b3cb285216519
+  data.tar.gz: 25a81544a107633c7c3c4459a1ab0f3e7c1a4c6092d5231b59a22ccbce55bb9b
 SHA512:
-  metadata.gz: a75daa528c2c263b4f5e1e2f57e81090a440c391860ef5bfc714967156cfe5b289c1b3d644428f5213e13c60fabca6745263d7cc6c7ba77c800d6177d8e1a888
-  data.tar.gz: 520875db136cfb2961b8bdee6f9948af3701aaef3eb318860ec7b7b018fd7ac500edc27ea0581765ce5e63e948dea842bd7a94a85ba3279323ec14fa21d91915
+  metadata.gz: dd0a131f94f7aec6ec700ad46ade522d37248d5475a23290d46b20f51025a5fd4043ccaf642fecdaeb387ef3cc85811282d0a52436dca6bdab1d8cbf23927211
+  data.tar.gz: 7597d199d6795c480d0b346ed021845993ad3f0bdd01fa9e6df1b129324c12c61dc181fa36f8990d85916016330d389413e6b6bdbeabb373c455e1ff4f3a1dfb

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 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.
+
 ## 0.2.2 2021-10-09
 
 **Changes**

data/README.md

@@ -1,15 +1,17 @@
 # pCloud API
 
 [![CI](https://github.com/jhunschejones/pcloud_api/actions/workflows/ci.yml/badge.svg)](https://github.com/jhunschejones/pcloud_api/actions/workflows/ci.yml)
+[![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
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'pcloud_api'
+gem "pcloud_api"
 ```
 
 And then execute:
@@ -28,6 +30,10 @@ Or install it yourself as:
 
 ## Usage
 
+### Generating an access token
+
+To use the `pcloud_api` client, you will need to first generate an access token. You may do this by cloning and running the script in [`./bin/generate_access_token`](https://github.com/jhunschejones/pcloud_api/blob/master/bin/generate_access_token). It will take you through the process of setting up a pCloud app and completing the OAuth2 flow in the browser.
+
 ### Configuration
 
 The `Pcloud::Client` can be configured by directly calling the `Pcloud::Client.configure` method in an initializer or somewhere else in your code at startup:
@@ -35,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
 )
 ```
 
@@ -46,43 +53,54 @@ There are two main objects represented in the library, `Pcloud::File` and `Pclou
 
 The `Pcloud::File` API includes:
 ```ruby
-# Find files by file id or path:
+# 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
-
-# Check if a file exists by id
+# 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)
 
 # Upload a new file, rename if one already exists with this name:
 Pcloud::File.upload(
-  folder_id: 1,
-  filename: "jack_goes_swimming.mp4",
+  path: "/Jack",
   file: File.open("/Users/joshua/Downloads/jack_goes_swimming.mp4")
 )
-# NOTE: the upload method will allow you to specify the :path or the :folder_id
-# or you can choose to pass neither paramenter and your files will be placed
-# in your root pCloud directory.
 
-# Upload a file, force overwrite of existing file:
+# Upload a file, force overwrite if a file already exists with this name:
 Pcloud::File.upload!(
-  folder_id: 1,
-  filename: "jack_goes_swimming.mp4",
+  path: "/Jack",
   file: File.open("/Users/joshua/Downloads/jack_goes_swimming.mp4")
 )
 
+# NOTE:
+# The `upload` and `upload!` methods will allow you to specify either the :path
+# or the :folder_id of the target parent directory, or you can choose to pass
+# neither paramenter and your files will be placed in your root pCloud
+# directory by default.
+
 # Rename a file:
 jack_goes_swimming.update(name: "That's one wet cat.mp4")
 
-# Move a file by updating the parent_folder_id or path:
+# Move a file by updating the :parent_folder_id:
 jack_goes_swimming.update(parent_folder_id: 9000)
 
+# Move a file by specifying the parent folder part of the path:
+jack_goes_swimming.update(path: "/photos/") # NOTE: needs to start and end with slashes
+
+# Move a file by specifying the entire new file path:
+jack_goes_swimming.update(path: "/photos/jack_goes_swimming.mp4")
+
 # Delete a file:
 jack_goes_swimming.delete
 
 # Get a link to download a file:
-jack_goes_swimming.download_link
+jack_goes_swimming.download_url
 
 # Access the parent folder of a file:
 jack_goes_swimming.parent_folder
@@ -90,27 +108,38 @@ jack_goes_swimming.parent_folder
 
 The `Pcloud::Folder` API is very similar:
 ```ruby
-# Find folders by folder id or path:
+# 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)
 
-# Create a new folder by parent_folder_id and name:
+# Create a new folder by :parent_folder_id and :name:
 Pcloud::Folder.first_or_create(parent_folder_id: 9000, name: "jack")
 
-# Create a new folder by path:
+# Create a new folder by :path (parent directory must already exist):
 Pcloud::Folder.first_or_create(path: "/images/jack")
 
 # Rename a folder:
 jack_images.update(name: "Jack's Photo Library")
 
-# Move a folder by updating the parent_folder_id or path:
+# Move a folder by updating the :parent_folder_id:
 jack_images.update(parent_folder_id: 9000)
 
+# Move a folder by specifying the parent folder part of the path:
+jack_images.update(path: "/photos/")
+# NOTES:
+# - Partial paths must start and end with slashes
+# - All refrenced parent directories in the path must already exist
+
+# Move a folder by specifying the entire new file path:
+jack_images.update(path: "/photos/images/jack")
+# NOTE: All refrenced parent directories in the path must already exist
+
 # Delete an empty folder:
 jack_images.delete
 
@@ -124,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
@@ -137,9 +166,77 @@ 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.)_
 
-### Generating an access token
+### Example uses
 
-To use the `pcloud_api` client, you will need to first generate an access token. You may do this by cloning and running the script in `./bin/generate_access_token`. It will take you through the process of setting up a pCloud app and completing the OAuth2 flow in the browser.
+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
 

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/Rakefile

@@ -3,4 +3,4 @@ require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+task default: :spec

data/lib/pcloud/client.rb

@@ -9,23 +9,24 @@ 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.merge!({ query: query }) unless query.empty?
-        options.merge!({ body: body }) unless body.empty?
+        options[:query] = query unless query.empty?
+        options[:body] = body unless body.empty?
         response = HTTParty.public_send(verb, "https://#{closest_server}/#{method}", options)
         json_response = JSON.parse(response.body)
         raise ErrorResponse.new(json_response["error"]) if json_response["error"]
@@ -34,17 +35,23 @@ 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 bearer token")
+        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"
@@ -53,7 +60,7 @@ module Pcloud
       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/file.rb

@@ -39,8 +39,8 @@ module Pcloud
       unless (params.keys - SUPPORTED_UPDATE_PARAMS).empty?
         raise InvalidParameters.new("Must be one of #{SUPPORTED_UPDATE_PARAMS}")
       end
-      if params[:path] && is_invalid_path_update_param?(params[:path])
-        raise InvalidParameter.new(":path param must start and end with `/`")
+      if params[:path] && params[:path][0] != "/"
+        raise InvalidParameter.new(":path param must start with `/`")
       end
       query = {
         fileid: id,
@@ -73,13 +73,6 @@ module Pcloud
       "#{@download_url}/#{URI.encode_www_form_component(name)}"
     end
 
-    private
-
-    def is_invalid_path_update_param?(path_param)
-      # Path params have to start and end with `/` when used with .update
-      [path_param[0], path_param[-1]] != ["/", "/"]
-    end
-
     class << self
       def exists?(id)
         find(id)
@@ -127,7 +120,7 @@ module Pcloud
             renameifexists: params[:overwrite] ? 0 : 1,
             path: params[:path],
             folderid: params[:folder_id],
-            filename: params.fetch(:filename),
+            filename: params[:filename],
             file: file,
           }.compact,
         )
@@ -136,7 +129,7 @@ module Pcloud
         # so we return just one file out of this method.
         uploaded_file = parse_many(response).first
         raise UploadFailed if uploaded_file.nil?
-        return uploaded_file
+        uploaded_file
       rescue KeyError => e
         missing_param = e.message.gsub("key not found: ", "")
         raise MissingParameter.new("#{missing_param} is required")

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
@@ -34,8 +34,8 @@ module Pcloud
       unless (params.keys - SUPPORTED_UPDATE_PARAMS).empty?
         raise InvalidParameters.new("Must be one of #{SUPPORTED_UPDATE_PARAMS}")
       end
-      if params[:path] && is_invalid_path_param?(params[:path])
-        raise InvalidParameter.new(":path parameter must start and end with `/`")
+      if params[:path] && params[:path][0] != "/"
+        raise InvalidParameter.new(":path parameter must start with `/`")
       end
       query = {
         folderid: id,
@@ -72,13 +72,6 @@ module Pcloud
       @contents
     end
 
-    private
-
-    def is_invalid_path_param?(path_param)
-      # Path params have to start and end with `/`
-      [path_param[0], path_param[-1]] != ["/", "/"]
-    end
-
     class << self
       def first_or_create(params)
         if params[:parent_folder_id] && params[:name]
@@ -98,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)
@@ -107,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.2"
+  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.2
+  version: 0.2.4
 platform: ruby
 authors:
 - Joshua Hunsche Jones
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-10-09 00:00:00.000000000 Z
+date: 2023-05-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -100,7 +100,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: 
+description:
 email:
 - joshua@hunschejones.com
 executables: []
@@ -134,7 +134,7 @@ metadata:
   homepage_uri: https://github.com/jhunschejones/pcloud_api
   source_code_uri: https://github.com/jhunschejones/pcloud_api
   changelog_uri: https://github.com/jhunschejones/pcloud_api/blob/master/CHANGELOG.md
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -149,8 +149,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.28
-signing_key: 
+rubygems_version: 3.3.26
+signing_key:
 specification_version: 4
 summary: A Ruby library for interacting with the pCloud API
 test_files: []