pcloud_api 0.1.0

checksums.yaml

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

data/.gitignore

@@ -0,0 +1,18 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+
+*.DS_Store
+Gemfile.lock
+
+# Don't accidentally check in builds or unpacked builds of this gem
+pcloud_api-*.gem
+pcloud_api-*/

data/.rspec

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

data/.travis.yml

@@ -0,0 +1,6 @@
+---
+language: ruby
+cache: bundler
+rvm:
+  - 2.7.2
+before_install: gem install bundler -v 1.17.3

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+## 0.1.0 2021-09-26
+
+* 1 major enhancement:
+  * Initial release

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in pcloud_api.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Joshua Hunsche Jones
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,137 @@
+# 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.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'pcloud_api'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install pcloud_api
+
+## Usage
+
+### 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:
+```ruby
+Pcloud::Client.configure(
+	access_token: "your-pcloud-app-access-token",
+	data_region: "EU"
+)
+```
+
+You may also choose to configure the client using the `PCLOUD_API_DATA_REGION` and `PCLOUD_API_ACCESS_TOKEN` environment variables if you prefer. Advanced users can also set additional configuration values including `PCLOUD_API_TIMEOUT_SECONDS` and `PCLOUD_API_BASE_URI`.
+
+### Available operations
+
+There are two main objects represented in the library, `Pcloud::File` and `Pcloud::Folder`. Both attempt to present an intuitive interface that will feel quickly familiar to Ruby and Ruby on Rails developers.
+
+The `Pcloud::File` API includes:
+```ruby
+# Find files by file id or path:
+Pcloud::File.find(1)
+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")
+)
+# 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
+# be placed in your root pCloud directory.
+
+# 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")
+)
+
+# 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:
+jack_goes_swimming.update(parent_folder_id: 9000)
+
+# Delete a file:
+jack_goes_swimming.delete
+
+# Get a link to download a file:
+jack_goes_swimming.download_link
+
+# Access the parent folder of a file:
+jack_goes_swimming.parent_folder
+```
+
+The `Pcloud::Folder` API is very similar:
+```ruby
+# Find folders by folder id or path:
+Pcloud::Folder.find(1)
+Pcloud::Folder.find_by(path: "/images")
+
+# 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:
+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:
+jack_images.update(parent_folder_id: 9000)
+
+# Delete an empty folder:
+jack_images.delete
+
+# Recursively delete a folder and all its contents:
+jack_images.delete!
+
+# Access the parent folder of a folder:
+jack_images.parent_folder
+
+# Access the contents of a folder:
+jack_images.contents
+```
+
+**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:**
+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.)
+
+### 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`. It will take you through the process of setting up a pCloud app and completing the OAuth2 flow in the browser.
+
+## 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.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/jhunschejones/pcloud_api.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/RELEASEING.md

@@ -0,0 +1,7 @@
+# Cutting a new release of the pCloud API gem:
+1. Update the gem version in `lib/pcloud/version.rb`.
+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`
+5. Publish the gem to rubygems.org: `gem push pcloud_api-<VERSION>.gem`.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "pcloud_api"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/generate_access_token

@@ -0,0 +1,46 @@
+#!/usr/bin/env ruby
+
+require "json"
+require "uri"
+require "net/http"
+
+class String
+  def green; "\033[32m#{self}\033[0m" end
+  def cyan;  "\033[36m#{self}\033[0m" end
+end
+
+puts "1. Register an app at `https://docs.pcloud.com/my_apps/`".cyan
+
+
+puts "2. Enter the client id and secret for the app:".cyan
+print "Client ID > "
+client_id = $stdin.gets.chomp.freeze
+print "Client Secret > "
+client_secret = $stdin.gets.chomp.freeze
+
+
+puts "3. Enter the data region of your pCloud account [EU/US]:".cyan
+print "> "
+region_specific_api_base = $stdin.gets.chomp == "EU" ? "eapi.pcloud.com" : "api.pcloud.com"
+
+
+puts "4. Navigate to this URL to start the access code flow:".cyan
+puts "`https://my.pcloud.com/oauth2/authorize?client_id=#{client_id}&response_type=code`"
+
+
+puts "5. After logging in, enter the access code provided below:".cyan
+print "> "
+access_code = $stdin.gets.chomp.freeze
+
+
+puts "6. Requesting access token from pCloud...".cyan
+query = { client_id: client_id, client_secret: client_secret, code: access_code }
+uri = URI.parse("https://#{region_specific_api_base}/oauth2_token?#{URI.encode_www_form(query)}")
+http = Net::HTTP.new(uri.host, uri.port)
+http.use_ssl = true
+request = Net::HTTP::Post.new(uri.request_uri)
+request["Accept"] = "application/json"
+response = http.request(request)
+json_response = JSON.parse(response.body)
+raise json_response["error"] if json_response["error"]
+puts "Done! Your access token is: #{json_response["access_token"]}".green

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/pcloud/client.rb

@@ -0,0 +1,68 @@
+module Pcloud
+  module Client
+    class ErrorResponse < StandardError; end
+    class ConfigurationError < StandardError; end
+
+    VALID_DATA_REGIONS = [
+      EU_DATA_REGION = "EU".freeze,
+      US_DATA_REGION = "US".freeze
+    ].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
+
+    class << self
+      def configure(access_token: nil, data_region: nil)
+        @@access_token = access_token
+        @@data_region = data_region
+        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
+        }
+        options.merge!({ query: query }) unless query.empty?
+        options.merge!({ 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"]
+        json_response
+      end
+
+      private
+
+      def data_region
+        @@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
+        @@access_token ||= ENV["PCLOUD_API_ACCESS_TOKEN"]
+        return @@access_token unless @@access_token.nil?
+        raise ConfigurationError.new("Missing bearer token")
+      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
+          when US_DATA_REGION
+            US_API_BASE
+          when EU_DATA_REGION
+            EU_API_BASE
+          else
+            raise ConfigurationError.new("Invalid pCloud data region, must be one of #{VALID_DATA_REGIONS}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pcloud/file/parser.rb

@@ -0,0 +1,44 @@
+module Pcloud
+  class File
+    module Parser
+      def self.included(base)
+        base.extend ClassMethods
+        base.include ClassMethods
+      end
+
+      module ClassMethods
+        def parse_one(response)
+          Pcloud::File.new(
+            id: response.dig("metadata", "fileid"),
+            path: response.dig("metadata", "path"),
+            name: response.dig("metadata", "name"),
+            content_type: response.dig("metadata", "contenttype"),
+            category_id: response.dig("metadata", "category"),
+            size: response.dig("metadata", "size"),
+            parent_folder_id: response.dig("metadata", "parentfolderid"),
+            is_deleted: response.dig("metadata", "isdeleted"),
+            created_at: response.dig("metadata", "created"),
+            modified_at: response.dig("metadata", "modified")
+          )
+        end
+
+        def parse_many(response)
+          response["metadata"].map do |metadata|
+            Pcloud::File.new(
+              id: metadata["fileid"],
+              path: metadata["path"],
+              name: metadata["name"],
+              content_type: metadata["contenttype"],
+              category_id: metadata["category"],
+              size: metadata["size"],
+              parent_folder_id: metadata["parentfolderid"],
+              is_deleted: metadata["isdeleted"],
+              created_at: metadata["created"],
+              modified_at: metadata["modified"]
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pcloud/file.rb

@@ -0,0 +1,137 @@
+module Pcloud
+  class File
+    class UnsuportedUpdateParams < StandardError; end
+    class ManformedUpdateParams < StandardError; end
+    class InvalidParameter < StandardError; end
+    class UploadFailed < StandardError; end
+    include Parser
+
+    SUPPORTED_UPDATE_PARAMS = [:name, :parent_folder_id, :path].freeze
+    FILE_CATAGORIES = {
+      "0" => "uncategorized",
+      "1" => "image",
+      "2" => "video",
+      "3" => "audio",
+      "4" => "document",
+      "5" => "archive",
+    }.freeze
+
+    attr_reader :id, :path, :name, :content_type, :category, :size,
+                :parent_folder_id, :is_deleted, :created_at, :modified_at
+
+    def initialize(params)
+      @id = params.fetch(:id)
+      @path = params.fetch(:path)
+      @name = params.fetch(:name)
+      @content_type = params.fetch(:content_type)
+      @category = FILE_CATAGORIES.fetch((params.fetch(:category_id) || 0).to_s)
+      @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)
+    end
+
+    def update(params)
+      unless (params.keys - SUPPORTED_UPDATE_PARAMS).empty?
+        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 `/`")
+      end
+      query = {
+        fileid: id,
+        tofolderid: params[:parent_folder_id] || nil,
+        toname: params[:name] || nil,
+        topath: params[:path] || nil
+      }.compact
+      parse_one(Client.execute("renamefile", query: query))
+    end
+
+    def delete
+      parse_one(Client.execute("deletefile", query: { fileid: id }))
+    end
+
+    def parent_folder
+      @parent_folder ||= Pcloud::Folder.find(parent_folder_id)
+    end
+
+    def download_url
+      @download_url ||= begin
+        file_url_parts = Client.execute(
+          "getfilelink",
+          query: { fileid: id, forcedownload: 1, skipfilename: 1 }
+        )
+        "https://#{file_url_parts["hosts"].first}#{file_url_parts["path"]}"
+      end
+      # This allows us to cache the expensive part of this method, requesting
+      # a download URL from pcloud, while maintaining consistency if the file
+      # name changes later.
+      "#{@download_url}/#{URI.encode_www_form_component(name)}"
+    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 find(id)
+        parse_one(Client.execute("stat", query: { fileid: id }))
+      end
+
+      def find_by(path:)
+        parse_one(Client.execute("stat", query: { path: path }))
+      end
+
+      def upload(filename:, file:, path: nil, folder_id: nil)
+        process_upload(
+          filename: filename,
+          file: file,
+          path: path,
+          folder_id: folder_id
+        )
+      end
+
+      def upload!(filename:, file:, path: nil, folder_id: nil)
+        process_upload(
+          filename: filename,
+          file: file,
+          path: path,
+          folder_id: folder_id,
+          overwrite: true
+        )
+      end
+
+      private
+
+      def process_upload(filename:, file:, path: nil, folder_id: nil, overwrite: false)
+        raise InvalidParameter.new("The `file` parameter must be an instance of Ruby `File`") unless file.is_a?(::File)
+
+        # === pCloud API behavior notes: ===
+        # 1. If neither `path` nor `folder_id` is provided, the file will be
+        #    uploaded into the users root directory by default.
+        # 2. If the `filename` does not match the name of the `file` provided,
+        #    pCloud will use the name of the `file` rather than renaming it.
+        response = Client.execute(
+          "uploadfile",
+          body: {
+            renameifexists: overwrite ? 0 : 1,
+            path: path,
+            folderid: folder_id,
+            filename: filename,
+            file: file
+          }.compact,
+        )
+        # This method on the pCloud API can accept multiple uploads at once.
+        # For now, this upload interface just takes a single file at a time
+        # 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
+      end
+    end
+  end
+end

data/lib/pcloud/folder/parser.rb

@@ -0,0 +1,51 @@
+module Pcloud
+  class Folder
+    module Parser
+      def self.included(base)
+        base.extend ClassMethods
+        base.include ClassMethods
+      end
+
+      module ClassMethods
+        def parse_one(response)
+          Pcloud::Folder.new(
+            id: response.dig("metadata", "folderid"),
+            path: response.dig("metadata", "path"),
+            name: response.dig("metadata", "name"),
+            parent_folder_id: response.dig("metadata", "parentfolderid"),
+            is_deleted: response.dig("metadata", "isdeleted"),
+            created_at: response.dig("metadata", "created"),
+            modified_at: response.dig("metadata", "modified"),
+            contents: (response.dig("metadata", "contents") || []).map do |content_item|
+              if content_item["isfolder"]
+                Pcloud::Folder.new(
+                  id: content_item["folderid"],
+                  path: content_item["path"], # no path comes back from this api
+                  name: content_item["name"],
+                  parent_folder_id: content_item["parentfolderid"],
+                  contents: content_item["contents"], # no content comes back from this api
+                  is_deleted: content_item["isdeleted"],
+                  created_at: content_item["created"],
+                  modified_at: content_item["modified"]
+                )
+              else
+                Pcloud::File.new(
+                  id: content_item["fileid"],
+                  path: content_item["path"],
+                  name: content_item["name"],
+                  content_type: content_item["contenttype"],
+                  category_id: content_item["category"],
+                  size: content_item["size"],
+                  parent_folder_id: content_item["parentfolderid"],
+                  is_deleted: content_item["isdeleted"],
+                  created_at: content_item["created"],
+                  modified_at: content_item["modified"]
+                )
+              end
+            end
+          )
+        end
+      end
+    end
+  end
+end

data/lib/pcloud/folder.rb

@@ -0,0 +1,99 @@
+module Pcloud
+  class Folder
+    class UnsuportedUpdateParams < StandardError; end
+    class ManformedUpdateParams < StandardError; end
+    class InvalidCreateParams < StandardError; end
+    include Parser
+
+    SUPPORTED_UPDATE_PARAMS = [:name, :parent_folder_id, :path].freeze
+
+    attr_reader :id, :path, :name, :parent_folder_id, :is_deleted, :created_at,
+                :modified_at
+
+    def initialize(params)
+      @id = params.fetch(:id)
+      @path = params.fetch(:path)
+      @name = params.fetch(:name)
+      @parent_folder_id = params.fetch(:parent_folder_id)
+      @contents = params.fetch(:contents)
+      # Some APIs (mainly recursive operations according to pCloud) return either a
+      # nil or an empty array of contents. In these cases, the @contents_are_confirmed
+      # flag is set to `false` in order to allow one retry to fetch the actual
+      # contents if the `contents` method is called on a folder object that does not
+      # 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)
+    end
+
+    def update(params)
+      unless (params.keys - SUPPORTED_UPDATE_PARAMS).empty?
+        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 `/`")
+      end
+      query = {
+        folderid: id,
+        tofolderid: params[:parent_folder_id] || nil,
+        toname: params[:name] || nil,
+        topath: params[:path] || nil
+      }.compact
+      parse_one(Client.execute("renamefolder", query: query))
+    end
+
+    # This method is the safest way to delte folders and will fail if the folder
+    # has contents.
+    def delete
+      parse_one(Client.execute("deletefolder", query: { folderid: id }))
+    end
+
+    # This method will delete a folder and recursively delete all its contents
+    def delete!
+      Client.execute("deletefolderrecursive", query: { folderid: id })
+      true # we don't get anything helpful back from pCloud on this request
+    end
+
+    def parent_folder
+      @parent_folder ||= Folder.find(parent_folder_id)
+    end
+
+    # Some APIs return `nil` or `[]` for contents when a folder does actually
+    # have contents. This method allows us to re-try one time if we try to get
+    # the contents and find that they're missing.
+    def contents
+      return @contents if @contents_are_confirmed
+      @contents = Folder.find(id).contents
+      @contents_are_confirmed = true
+      @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]
+          parse_one(Client.execute("createfolderifnotexists", query: { folderid: params[:parent_folder_id], name: params[:name] }))
+        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")
+        end
+      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 }))
+      end
+    end
+  end
+end

data/lib/pcloud/version.rb

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

data/lib/pcloud_api.rb

@@ -0,0 +1,9 @@
+require "httparty"
+require "json"
+
+require "pcloud/version"
+require "pcloud/file/parser"
+require "pcloud/file"
+require "pcloud/folder/parser"
+require "pcloud/folder"
+require "pcloud/client"

data/pcloud_api.gemspec

@@ -0,0 +1,33 @@
+require_relative 'lib/pcloud/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "pcloud_api"
+  spec.version       = Pcloud::VERSION
+  spec.authors       = ["Joshua Hunsche Jones"]
+  spec.email         = ["joshua@hunschejones.com"]
+
+  spec.summary       = "A Ruby library for interacting with the pCloud API"
+  spec.homepage      = "https://github.com/jhunschejones/pcloud_api"
+  spec.license       = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/jhunschejones/pcloud_api"
+  spec.metadata["changelog_uri"] = "https://github.com/jhunschejones/pcloud_api/blob/master/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", ">= 1.17", "< 3.0"
+  spec.add_development_dependency "rake", "~> 12.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "pry", "~> 0.13"
+
+  spec.add_dependency "httparty", "~> 0.16"
+end

metadata

@@ -0,0 +1,142 @@
+--- !ruby/object:Gem::Specification
+name: pcloud_api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Joshua Hunsche Jones
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2021-09-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.17'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.17'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+description: 
+email:
+- joshua@hunschejones.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- RELEASEING.md
+- Rakefile
+- bin/console
+- bin/generate_access_token
+- bin/setup
+- lib/pcloud/client.rb
+- lib/pcloud/file.rb
+- lib/pcloud/file/parser.rb
+- lib/pcloud/folder.rb
+- lib/pcloud/folder/parser.rb
+- lib/pcloud/version.rb
+- lib/pcloud_api.rb
+- pcloud_api.gemspec
+homepage: https://github.com/jhunschejones/pcloud_api
+licenses:
+- MIT
+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: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.28
+signing_key: 
+specification_version: 4
+summary: A Ruby library for interacting with the pCloud API
+test_files: []