kloudless 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: aadd0e43b6426a49c8172bbc0e5f5dcae993744c
+  data.tar.gz: 69dde9fd66257fa64f3a05e87ab8fa7c88596695
+SHA512:
+  metadata.gz: 4c61c7453b87e8e0b8e333d91ecfb8dd1783433a183882764ec13287f9c5e409f30cb06cbcdae9836ff10cf3da786ccf5a00ffc8fdc7ce50cb738b31a9f76b96
+  data.tar.gz: c487c4ce1952757c2c84e332c3d6294b6a17f84b51df1b343fba952b329a4b68dc0add13763c45783c097d1200e8ec0beb907b57a6ffcc7b429a044a40cb87a7

data/.gitignore

@@ -0,0 +1,22 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Jerry Cheung
+
+MIT License
+
+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,62 @@
+# Kloudless
+
+Kloudless API Ruby client.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'kloudless'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install kloudless
+
+## Usage
+
+See the [Kloudless API Docs](https://developers.kloudless.com/docs) for the
+official reference. You can obtain an API Key at the [Developer
+Portal](https://developers.kloudless.com/).
+
+```ruby
+# Authentication
+Kloudless.authorize(api_key: "abc")
+
+accounts = Kloudless::Account.list
+account = accounts.first
+
+account = Kloudless::Account.update(account_id: account.id, active: false)
+Kloudless::Account.delete(account_id: account.id)
+```
+
+## Version
+
+This gem uses [semantic versioning](http://semver.org), where a version number
+looks like:
+
+```
+v major.minor.patch
+```
+
+The major version tracks the version of the Kloudless API. For example, all
+versions that start with `v0.x.y` are compatible with Kloudless API `v0`.
+
+## Release
+
+To release this gem, look under the `script` directory. Check out
+[jch/release-scripts](https://github.com/jch/release-scripts) for details.
+
+## Contributing
+
+[TODO.md](TODO.md) has a list of things to work on. File an issue or pull
+request if you'd like to discuss or tackle any of those tasks.
+
+1. Fork it ( https://github.com/[my-github-username]/kloudless/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new [Pull Request](https://help.github.com/send-pull-requests/)

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+end
+
+task :default => :test

data/TODO.md

@@ -0,0 +1,26 @@
+# TODO
+
+- TravisCI
+- parameter checking
+- README: examples, design, references
+- publish gem
+- rdoc/yard documentation
+- support ruby 2.0? 1.9? (Only thing block this is I use required kwargs from 2.1)
+- what should #delete return? boolean, Response object?
+- associations between models. e.g. Account#files
+- Folder#retrieve should distinguish between subfolders and files
+- webhooks?
+- integration tests that can be run locally
+- File#update not implemented
+- Model attribute setters. e.g. f = File.new; f.name = '3'
+- Object oriented style sugar interface: f = File.new; f.save (does create or update)
+- `find . -type f | xargs grep 'TODO'` for more
+
+## Doc errors
+
+- https://developers.kloudless.com/docs#files-list-recent-files takes multiple account ids
+- https://developers.kloudless.com/docs#multipart-upload says files larger than 5MB, but https://developers.kloudless.com/docs#files-upload-a-file says 100MB
+- https://developers.kloudless.com/docs#multipart-upload-initialize-multipart-session is missing required parent_id
+- 'multipart_id' is better variable name? https://developers.kloudless.com/docs#multipart-upload-retrieve-multipart-session-information
+- All other models are create, but Account is import https://developers.kloudless.com/docs#accounts-import-an-account
+- events aren't really a collection. e.g. doesn't have total, count, only cursor

data/kloudless.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'kloudless/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "kloudless"
+  spec.version       = Kloudless::VERSION
+  spec.authors       = ["Jerry Cheung"]
+  spec.email         = ["jollyjerry@gmail.com"]
+  spec.summary       = %q{Kloudless API client}
+  spec.homepage      = "https://github.com/jch/kloudless"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 2.1"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^test/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "byebug"
+  spec.add_development_dependency "minitest"
+end

data/lib/kloudless.rb

@@ -0,0 +1,50 @@
+require_relative "kloudless/collection"
+require_relative "kloudless/error"
+require_relative "kloudless/http"
+require_relative "kloudless/model"
+require_relative "kloudless/account"
+require_relative "kloudless/account_key"
+require_relative "kloudless/team"
+require_relative "kloudless/file"
+require_relative "kloudless/multipart_upload"
+require_relative "kloudless/folder"
+require_relative "kloudless/link"
+require_relative "kloudless/event"
+require_relative "kloudless/version"
+require "json"
+require "uri"
+
+module Kloudless
+  API_VERSION = "v0".freeze
+  API_URL = "https://api.kloudless.com/#{API_VERSION}".freeze
+
+  # Public: Authorize with API Key or Account Key. Returns nothing.
+  #
+  # Options:
+  #  :api_key
+  #  :account_key
+  #
+  # https://developers.kloudless.com/docs#authorization
+  def self.authorize(options = {})
+    Kloudless::HTTP.headers["Authorization"] = if options[:api_key]
+      "ApiKey #{options[:api_key]}"
+    elsif options[:account_key]
+      "AccountKey #{options[:account_key]}"
+    else
+      raise ArgumentError.new(":api_key or :account_key required")
+    end
+  end
+
+  # Internal: HTTP client for easier mocking
+  def self.http
+    @http || Kloudless::HTTP
+  end
+
+  def self.http=(client)
+    @http = client
+  end
+
+  def http
+    self.class.http
+  end
+end

data/lib/kloudless/account.rb

@@ -0,0 +1,33 @@
+module Kloudless
+  # Each account represents a cloud storage account that a user has connected to
+  # your app.
+  #
+  # https://developers.kloudless.com/docs#accounts
+  class Account < Model
+    # Public: Returns Kloudless::Collection. Raises Kloudless::Error.
+    def self.list(params = {})
+      Kloudless::Collection.new(self, http.get("/accounts", params: params))
+    end
+
+    def self.retrieve(account_id:, **params)
+      new(http.get("/accounts/#{account_id}", params: params))
+    end
+
+    def self.update(account_id:, **params)
+      new(http.patch("/accounts/#{account_id}", params: params))
+    end
+
+    def self.delete(account_id:)
+      new(http.delete("/accounts/#{account_id}"))
+    end
+
+    # Public: TODO: Returns ???. Raises Kloudless::Error.
+    def self.import(params = {})
+      http.post("/accounts", params: params)
+    end
+
+    class << self
+      alias_method :create, :import
+    end
+  end
+end

data/lib/kloudless/account_key.rb

@@ -0,0 +1,26 @@
+module Kloudless
+  # Account Keys can be used instead of API Keys to restrict access to a
+  # specific account’s data. This is most useful for client-side requests.
+  #
+  # https://developers.kloudless.com/docs#account-keys
+  class AccountKey < Model
+    # Public: Returns Kloudless::Collection of AccountKey. Raises
+    # Kloudless::Error.
+    #
+    #  :account_ids - Array of account_ids to fetch keys for
+    def self.list(account_ids:, **params)
+      path = "/accounts/#{account_ids.join(',')}/keys"
+      Kloudless::Collection.new(self, http.get(path, params: params))
+    end
+
+    def self.retrieve(account_id:, key_id:, **params)
+      path = "/accounts/#{account_id}/keys/#{key_id}"
+      new(http.get(path, params: params))
+    end
+
+    def self.delete(account_id:, key_id:)
+      path = "/accounts/#{account_id}/keys/#{key_id}"
+      new(http.delete(path))
+    end
+  end
+end

data/lib/kloudless/collection.rb

@@ -0,0 +1,32 @@
+module Kloudless
+  class Collection
+    include Enumerable
+
+    def initialize(model, json)
+      @model = model
+      @json = json
+    end
+
+    def total
+      @json["total"]
+    end
+
+    def count
+      @json["count"]
+    end
+
+    def page
+      @json["page"]
+    end
+
+    def objects
+      @json["objects"]
+    end
+
+    def each
+      @json["objects"].each do |attrs|
+        yield @model.new(attrs)
+      end
+    end
+  end
+end

data/lib/kloudless/error.rb

@@ -0,0 +1,172 @@
+module Kloudless
+  # All errors inherit from Kloudless::Error. You may rescue this class as a
+  # catch all. Specific errors are documented in
+  # https://developers.kloudless.com/docs#errors
+  #
+  #  begin
+  #    # ... some api action
+  #  rescue Kloudless::Error => e
+  #    $stderr.puts e.status_code  # 401
+  #    $stderr.puts e.error_code   # 'unauthorized'
+  #    $stderr.puts e.id           # id of request that caused the error
+  #    $stderr.puts e.conflicting_resource_id
+  #    $stderr.puts e.message
+  #  end
+  #
+  class Error < RuntimeError
+    # Public: e.g. 400, 401, 500, 4xx-5xx.
+    attr_accessor :status_code
+
+    # Public: short string name of error. e.g. bad_request, request_failed
+    attr_accessor :error_code
+
+    # Public: identifier of request that caused the error
+    attr_accessor :id
+
+    # Public: identitifer of resource request conflicted with. See 409.
+    attr_accessor :conflicting_resource_id
+
+    # Internal: `json` is a Hash. Returns an instantiated subclass of
+    # Kloudless::Error.
+    def self.from_json(json)
+      error_class = ERRORS.fetch(json["error_code"].to_sym, UnknownError)
+      error = error_class.new(json["message"])
+      error.error_code = json["error_code"]
+      error.status_code = json["status_code"]
+      error.id = json["id"]
+      error.conflicting_resource_id = json["conflicting_resource_id"]
+      error
+    end
+  end
+
+  # 400  The request is malformed. Check the message for the reason.
+  class BadRequestError < Error; end
+
+  # 400  The request failed. Check the message for the reason.
+  class RequestFailedError < Error; end
+
+  # 400  Invalid parent folder_id parameter.
+  class InvalidParentFolderError < Error; end
+
+  # 400  The request is malformed: the parameters are incorrect.
+  class InvalidParametersError < Error; end
+
+  # 400  The resource_type provided is not correct.
+  class InvalidResourceTypeError < Error; end
+
+  # 401  The Kloudless credentials or token provided are invalid.
+  class UnauthorizedError < Error; end
+
+  # 401  The credentials or token provided for the upstream cloud storage
+  # service are invalid.
+  class ServiceUnauthorizedError < Error; end
+
+  # 401  An authorization parameter is missing.
+  class AuthenticationRequiredError < Error; end
+
+  # 401  Invalid request token provided.
+  class InvalidTokenError < Error; end
+
+  # 403  Cannot delete the folder as it is not empty and the recursive parameter is not set to True.
+  class FolderNotEmptyError < Error; end
+
+  # 403  Unable to access resource.
+  class PermissionDeniedError < Error; end
+
+  # 403  Forbidden request made to Kloudless.
+  class ForbiddenError < Error; end
+
+  # 403  Forbidden request made to the upstream cloud storage service.
+  class ServiceForbiddenError < Error; end
+
+  # 404  The requested resource was not found.
+  class NotFoundError < Error; end
+
+  # 405  The request was made using an unsupported method.
+  class MethodNotAllowedError < Error; end
+
+  # 406  The request was made with unacceptable data.
+  class NotAcceptableError < Error; end
+
+  # 409  Resource already exists. Checking the conflicting_resource_id
+  # parameter in the response.
+  class NamingConflictError < Error; end
+
+  # 429  Too many requests to the Kloudless API were made. Check the
+  # Retry-After header.
+  class TooManyRequestsError < Error; end
+
+  # 429  Too many requests to the underlying service API were made. Check the Retry-After header.
+  class TooManyServiceRequestsError < Error; end
+
+  # 500  The request was made by Kloudless with an unsupported method.*
+  class MethodNotAllowedError < Error; end
+
+  # 500  The request was made by Kloudless with unacceptable data.*
+  class NotAcceptableError < Error; end
+
+  # 500  Kloudless experienced an internal error.*
+  class InternalErrorError < Error; end
+
+  # 500  Kloudless experienced an error retrieving link data.*
+  class LinkErrorError < Error; end
+
+  # 500  Kloudless experienced an error making an invalid request.*
+  class UnsupportedMediaTypeError < Error; end
+
+  # 501  The request method is not currently implemented for the cloud storage service.
+  class NotImplementedError < Error; end
+
+  # 502  Kloudless received an invalid response from the upstream cloud storage service.
+  class BadGatewayError < Error; end
+
+  # 503  The upstream cloud storage service is unavailable.
+  class ServiceNotAvailableError < Error; end
+
+  # 504  The upstream cloud storage service is unavailable.
+  class GatewayTimeoutError < Error; end
+
+  # 507  There is not enough free space in the cloud storage account to complete the request.
+  class InsufficientStorageError < Error; end
+
+  # We should never see this error. This means the API added an error we don't
+  # know about.
+  class UnknownError < Error; end
+
+  class Error
+    # We could use ActiveSupport::Inflector here, but didn't want to bring in a
+    # dependency. To regenerate, copy from docs, and run:
+    #
+    # pbpaste | ruby -r'active_support/core_ext/string/inflections' -ne 'puts "#{$_.chomp}: #{$_.classify.chomp},"'
+    ERRORS = {
+      bad_request: BadRequestError,
+      request_failed: RequestFailedError,
+      invalid_parent_folder: InvalidParentFolderError,
+      invalid_parameters: InvalidParametersError,
+      invalid_resource_type: InvalidResourceTypeError,
+      unauthorized: UnauthorizedError,
+      service_unauthorized: ServiceUnauthorizedError,
+      authentication_required: AuthenticationRequiredError,
+      invalid_token: InvalidTokenError,
+      folder_not_empty: FolderNotEmptyError,
+      permission_denied: PermissionDeniedError,
+      forbidden: ForbiddenError,
+      service_forbidden: ServiceForbiddenError,
+      not_found: NotFoundError,
+      method_not_allowed: MethodNotAllowedError,
+      not_acceptable: NotAcceptableError,
+      naming_conflict: NamingConflictError,
+      too_many_requests: TooManyRequestsError,
+      too_many_service_requests: TooManyServiceRequestsError,
+      method_not_allowed: MethodNotAllowedError,
+      not_acceptable: NotAcceptableError,
+      internal_error: InternalErrorError,
+      link_error: LinkErrorError,
+      unsupported_media_type: UnsupportedMediaTypeError,
+      not_implemented: NotImplementedError,
+      bad_gateway: BadGatewayError,
+      service_not_available: ServiceNotAvailableError,
+      gateway_timeout: GatewayTimeoutError,
+      insufficient_storage: InsufficientStorageError    }
+  end
+end