pcloud_api 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5ea6aab35912a377555ea6ee45e36ec29dbc797e620b4d738ea2665f2679e79
-  data.tar.gz: 5bf4514161d144db50fbbd919e8886e1adc3144e9df7381db23a7594170c1cca
+  metadata.gz: 0bc6a66525cb7bfd47085851a95dbc1656759f92960611d1d66e5f466025c800
+  data.tar.gz: 3eb54b53ab7c2c97ece4db9a074cbf75d6aa602ba727c917a6f88dbc97997c92
 SHA512:
-  metadata.gz: 23121677b95b60944d49d59623466841d08a7c1e1833013f6eaf6ca8e011799a26bc6bfadeb28b6c7c65e178cb51f5632e78ed76a2cd547a6d2d875dbbb4d1b8
-  data.tar.gz: f1900eaf066f7dba20e6b8ef9b0bfa3554e070d5f0ca2b3bbd7cb5d858cbbcb405e60c144ace91048c3635658752fd4ab232af068f058e835b7ac0e2fd23db83
+  metadata.gz: 0ce986fc8cdedaed9773209c26afbaf08091d4285abbb40126a0fcc0fcac99d77bd1ce1250bed6cdce4dd79e445076ca49469f6ce0c2e3ccfb597a36bf41f79f
+  data.tar.gz: 5aa4fb9d5dd96227b61c18c2bc537ad4b73338509e8a0e6b710cc06415228c41f67efb7719258ae954eb0fe9f36fae55d9151622021fb1f4d8116767aae1cad8

data/CHANGELOG.md

@@ -1,4 +1,13 @@
+## 0.2.0 2021-09-26
+
+New
+  * An `.exists?` method has been added to `Pcloud::Folder` and `Pcloud::File`
+  * The `.find_by` method on `Pcloud::Folder` and `Pcloud::File` can now be called with either `:id` or `:path`. NOTE: pCloud treats `:id` with precedence, so an error will be raised if the method is called with both parameters at once. _(Allowing precedence in a method like this would likely feel like unexpected behavior, so my intention was to make it immediately obvious to the end user.)_
+
+Change
+ * `Pcloud::Folder` and `Pcloud::File` `created_at` and `modified_at` timestamps are now returned as Ruby `Time` objects
+ * Some error class names and messages have been cleaned up for additional clarity and consistency.
+
 ## 0.1.0 2021-09-26
 
-* 1 major enhancement:
-  * Initial release
+Initial release

data/README.md

@@ -25,8 +25,8 @@ Or install it yourself as:
 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:
 ```ruby
 Pcloud::Client.configure(
-	access_token: "your-pcloud-app-access-token",
-	data_region: "EU"
+  access_token: "your-pcloud-app-access-token",
+  data_region: "EU"
 )
 ```
 
@@ -44,9 +44,9 @@ Pcloud::File.find_by(path: "/images/jack_the_cat.jpg")
 
 # Upload a new file, rename if already existing:
 Pcloud::File.upload(
-	folder_id: 1,
-	filename: "jack_goes_swimming.mp4",
-	file: File.open("/Users/joshua/Downloads/jack_goes_swimming.mp4")
+  folder_id: 1,
+  filename: "jack_goes_swimming.mp4",
+  file: File.open("/Users/joshua/Downloads/jack_goes_swimming.mp4")
 )
 # NOTE: the upload method will allow you to specify either the `path` or the
 # `folder_id`, or you can choose to pass neither paramenter and your files will
@@ -54,9 +54,9 @@ Pcloud::File.upload(
 
 # Upload a file, force overwrite of existing file:
 Pcloud::File.upload!(
-	folder_id: 1,
-	filename: "jack_goes_swimming.mp4",
-	file: File.open("/Users/joshua/Downloads/jack_goes_swimming.mp4")
+  folder_id: 1,
+  filename: "jack_goes_swimming.mp4",
+  file: File.open("/Users/joshua/Downloads/jack_goes_swimming.mp4")
 )
 
 # Rename a file:
@@ -106,16 +106,18 @@ jack_images.parent_folder
 jack_images.contents
 ```
 
-**Aside: path vs id:**
+**Aside: 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.
 
 
-**Aside: off-label client use:**
+**Aside: 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
 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.)
+_(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
 

data/lib/pcloud/file.rb

@@ -1,10 +1,13 @@
 module Pcloud
   class File
-    class UnsuportedUpdateParams < StandardError; end
     class ManformedUpdateParams < StandardError; end
     class InvalidParameter < StandardError; end
+    class InvalidParameters < StandardError; end
+    class MissingParameter < StandardError; end
     class UploadFailed < StandardError; end
+
     include Parser
+    include Pcloud::TimeHelper
 
     SUPPORTED_UPDATE_PARAMS = [:name, :parent_folder_id, :path].freeze
     FILE_CATAGORIES = {
@@ -28,16 +31,16 @@ module Pcloud
       @size = params.fetch(:size) # bytes
       @parent_folder_id = params.fetch(:parent_folder_id)
       @is_deleted = params.fetch(:is_deleted) || false
-      @created_at = params.fetch(:created_at)
-      @modified_at = params.fetch(:modified_at)
+      @created_at = time_from(params.fetch(:created_at))
+      @modified_at = time_from(params.fetch(:modified_at))
     end
 
     def update(params)
       unless (params.keys - SUPPORTED_UPDATE_PARAMS).empty?
-        raise UnsuportedUpdateParams.new("Must be one of #{SUPPORTED_UPDATE_PARAMS}")
+        raise InvalidParameters.new("Must be one of #{SUPPORTED_UPDATE_PARAMS}")
       end
       if params[:path] && is_invalid_path_param?(params[:path])
-        raise ManformedUpdateParams.new("`path` param must start and end with `/`")
+        raise ManformedUpdateParams.new(":path param must start and end with `/`")
       end
       query = {
         fileid: id,
@@ -73,41 +76,46 @@ module Pcloud
     private
 
     def is_invalid_path_param?(path_param)
-      # Path params have to start and end with `/``
+      # Path params have to start and end with `/`
       [path_param[0], path_param[-1]] != ["/", "/"]
     end
 
     class << self
+      def exists?(id)
+        find(id)
+        true
+      rescue Pcloud::Client::ErrorResponse => e
+        return false if e.message == "File not found."
+        raise e
+      end
+
       def find(id)
         parse_one(Client.execute("stat", query: { fileid: id }))
       end
 
-      def find_by(path:)
-        parse_one(Client.execute("stat", query: { path: path }))
+      def find_by(params)
+        raise MissingParameter.new(":path or :id is required") unless params[:path] || params[:id]
+        raise InvalidParameters.new(":id takes precedent over :path, please only use one or the other") if params[:path] && params[:id]
+        parse_one(
+          Client.execute(
+            "stat",
+            query: { path: params[:path], fileid: params[:id] }.compact
+          )
+        )
       end
 
-      def upload(filename:, file:, path: nil, folder_id: nil)
-        process_upload(
-          filename: filename,
-          file: file,
-          path: path,
-          folder_id: folder_id
-        )
+      def upload(params)
+        process_upload(params)
       end
 
-      def upload!(filename:, file:, path: nil, folder_id: nil)
-        process_upload(
-          filename: filename,
-          file: file,
-          path: path,
-          folder_id: folder_id,
-          overwrite: true
-        )
+      def upload!(params)
+        process_upload(params.merge({ overwrite: true }))
       end
 
       private
 
-      def process_upload(filename:, file:, path: nil, folder_id: nil, overwrite: false)
+      def process_upload(params)
+        file = params.fetch(:file)
         raise InvalidParameter.new("The `file` parameter must be an instance of Ruby `File`") unless file.is_a?(::File)
 
         # === pCloud API behavior notes: ===
@@ -118,11 +126,11 @@ module Pcloud
         response = Client.execute(
           "uploadfile",
           body: {
-            renameifexists: overwrite ? 0 : 1,
-            path: path,
-            folderid: folder_id,
-            filename: filename,
-            file: file
+            renameifexists: params[:overwrite] ? 0 : 1,
+            path: params[:path],
+            folderid: params[:folder_id],
+            filename: params.fetch(:filename),
+            file: file,
           }.compact,
         )
         # This method on the pCloud API can accept multiple uploads at once.
@@ -131,6 +139,9 @@ module Pcloud
         uploaded_file = parse_many(response).first
         raise UploadFailed if uploaded_file.nil?
         return uploaded_file
+      rescue KeyError => e
+        missing_param = e.message.gsub("key not found: ", "")
+        raise MissingParameter.new("#{missing_param} is required")
       end
     end
   end

data/lib/pcloud/folder.rb

@@ -2,8 +2,11 @@ module Pcloud
   class Folder
     class UnsuportedUpdateParams < StandardError; end
     class ManformedUpdateParams < StandardError; end
-    class InvalidCreateParams < StandardError; end
+    class InvalidParameters < StandardError; end
+    class MissingParameter < StandardError; end
+
     include Parser
+    include Pcloud::TimeHelper
 
     SUPPORTED_UPDATE_PARAMS = [:name, :parent_folder_id, :path].freeze
 
@@ -23,8 +26,8 @@ module Pcloud
       # have any contents set yet.
       @contents_are_confirmed = @contents && @contents.size > 0
       @is_deleted = params.fetch(:is_deleted) || false
-      @created_at = params.fetch(:created_at)
-      @modified_at = params.fetch(:modified_at)
+      @created_at = time_from(params.fetch(:created_at))
+      @modified_at = time_from(params.fetch(:modified_at))
     end
 
     def update(params)
@@ -32,7 +35,7 @@ module Pcloud
         raise UnsuportedUpdateParams.new("Must be one of #{SUPPORTED_UPDATE_PARAMS}")
       end
       if params[:path] && is_invalid_path_param?(params[:path])
-        raise ManformedUpdateParams.new("`path` param must start and end with `/`")
+        raise ManformedUpdateParams.new(":path param must start and end with `/`")
       end
       query = {
         folderid: id,
@@ -72,7 +75,7 @@ module Pcloud
     private
 
     def is_invalid_path_param?(path_param)
-      # Path params have to start and end with `/``
+      # Path params have to start and end with `/`
       [path_param[0], path_param[-1]] != ["/", "/"]
     end
 
@@ -83,16 +86,31 @@ module Pcloud
         elsif params[:path]
           parse_one(Client.execute("createfolderifnotexists", query: { path: params[:path] }))
         else
-          raise InvalidCreateParams.new("first_or_create must be called with either `path` or both `parent_folder_id` and `name` params")
+          raise InvalidParameters.new("either :path or a combination of :parent_folder_id and :name params are required")
         end
       end
 
+      def exists?(id)
+        find(id)
+        true
+      rescue Pcloud::Client::ErrorResponse => e
+        return false if e.message == "Directory does not exist."
+        raise e
+      end
+
       def find(id)
         parse_one(Client.execute("listfolder", query: { folderid: id }))
       end
 
-      def find_by(path:)
-        parse_one(Client.execute("listfolder", query: { path: path }))
+      def find_by(params)
+        raise MissingParameter.new(":path or :id is required") unless params[:path] || params[:id]
+        raise InvalidParameters.new(":id takes precedent over :path, please only use one or the other") if params[:path] && params[:id]
+        parse_one(
+          Client.execute(
+            "listfolder",
+            query: { path: params[:path], folderid: params[:id] }.compact
+          )
+        )
       end
     end
   end

data/lib/pcloud/time_helper.rb

@@ -0,0 +1,26 @@
+module Pcloud
+  module TimeHelper
+    class UnrecognizedTimeFormat < StandardError; end
+
+    TIMEZONE = TZInfo::Timezone.get(ENV.fetch("TZ", "UTC")).freeze
+
+    protected
+
+    def time_from(time)
+      time_object =
+        if time.is_a?(String)
+          Time.parse(time)
+        elsif time.is_a?(Integer)
+          return Time.at(time) if time.digits.size < 13
+          milliseconds = time.to_s[-3..-1].to_i
+          seconds = time.to_s[0..-4].to_i
+          Time.at(seconds, milliseconds, :millisecond)
+        elsif time.is_a?(Time)
+          time
+        else
+          raise Pcloud::TimeHelper::UnrecognizedTimeFormat.new(time.inspect)
+        end
+      TIMEZONE.to_local(time_object)
+    end
+  end
+end

data/lib/pcloud/version.rb

@@ -1,3 +1,3 @@
 module Pcloud
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/pcloud_api.rb

@@ -1,7 +1,9 @@
 require "httparty"
+require "tzinfo"
 require "json"
 
 require "pcloud/version"
+require "pcloud/time_helper"
 require "pcloud/file/parser"
 require "pcloud/file"
 require "pcloud/folder/parser"

data/pcloud_api.gemspec

@@ -30,4 +30,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "pry", "~> 0.13"
 
   spec.add_dependency "httparty", "~> 0.16"
+  spec.add_dependency "tzinfo"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pcloud_api
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Joshua Hunsche Jones
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-09-27 00:00:00.000000000 Z
+date: 2021-10-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -86,6 +86,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.16'
+- !ruby/object:Gem::Dependency
+  name: tzinfo
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: 
 email:
 - joshua@hunschejones.com
@@ -110,6 +124,7 @@ files:
 - lib/pcloud/file/parser.rb
 - lib/pcloud/folder.rb
 - lib/pcloud/folder/parser.rb
+- lib/pcloud/time_helper.rb
 - lib/pcloud/version.rb
 - lib/pcloud_api.rb
 - pcloud_api.gemspec