wordpress_client 0.0.1 → 2.0.1

data/README.md

@@ -1,24 +1,31 @@
 # WordpressClient
 
-WordpressClient is a very simple client to the Wordpress API, version 2 beta 8.0.
+> :warning: **This project is in "maintenance mode" meaning that no patches will be accepted unless security related. We do not recommend using this gem, current users are recommended to migrate to another solution.**
 
-**NOTE:** The repository is still named `wpclient` as we're in the middle of a rename. Some references might persist until it's completed.
+WordpressClient is a very simple client for the Wordpress [REST API][api].
 
-[![Circle CI](https://circleci.com/gh/hemnet/wpclient.svg?style=svg)](https://circleci.com/gh/hemnet/wpclient) [![Code Climate](https://codeclimate.com/repos/5645938269568041da00cded/badges/5e870b57428f23c1f2ff/gpa.svg)](https://codeclimate.com/repos/5645938269568041da00cded/feed) [![Test Coverage](https://codeclimate.com/repos/5645938269568041da00cded/badges/5e870b57428f23c1f2ff/coverage.svg)](https://codeclimate.com/repos/5645938269568041da00cded/coverage)
+[![Circle CI](https://circleci.com/gh/hemnet/wordpress_client.svg?style=svg)](https://circleci.com/gh/hemnet/wordpress_client) [![Code Climate](https://codeclimate.com/repos/5645938269568041da00cded/badges/5e870b57428f23c1f2ff/gpa.svg)](https://codeclimate.com/repos/5645938269568041da00cded/feed) [![Gem Version](https://badge.fury.io/rb/wordpress_client.svg)](https://badge.fury.io/rb/wordpress_client)
 
 ## Usage
 
-Initialize a client with a username, password and API URL. You can then search for posts.
+**[Read the full API documentation][docs]**
+
+Initialize a client with a user name, password and API URL. You can then search
+for posts.
 
 ```ruby
-client = WordpressClient.new(url: "https://example.com/wp-json/", username: "example", password: "example")
+client = WordpressClient.new(
+  url: "https://example.com/wp-json/",
+  username: "example",
+  password: "example",
+)
 
 client.posts(per_page: 5) # => [WordpressClient::Post, WordpressClient::Post]
 ```
 
 ### Creating a post
 
-You can create posts by calling `create_post`. If you supply a ID, the article will be created using `PUT` instead of `POST`.
+You can create posts by calling `create_post`.
 
 ```ruby
 data = {
@@ -29,20 +36,24 @@ data = {
 post = client.create_post(data) # => WordpressClient::Post
 updated_post = client.update_post(post.id, title: "Updated") # => WordpressClient::Post
 
+updated_post.author # => "Name"
 updated_post.title_html # => "Updated"
 ```
 
 ## Running tests
 
-You need to install Docker and set it up for your machine. Note that you need `docker-machine` to run Docker on OS X.
+You need to install Docker and set it up for your machine.
 
-Run tests using the normal `rspec` command after installing all bundles. The first time the integration tests are run, a docker image will be built that hosts a Wordpress installation, but the image will be re-used on subsequent runs.
+Run tests using the normal `rspec` command after installing all bundles.
 
 ```
 bundle exec rspec
 ```
 
-You can also run `bundle exec guard` to have tests run automatically when you change files in the repo. If you tag your examples with `focus: true`, Guard will only run those tests. This can help when doing very focused coding, but remember to remove the filter before you commit and let the entire suite run.
+You can also run `bundle exec guard` to have tests run automatically when you
+change files in the repo. If you tag your examples with `focus: true`, Guard
+will only run those tests. This can help when doing very focused coding, but
+remember to remove the filter before you commit and let the entire suite run.
 
 ```ruby
 describe Foo, focus: true do
@@ -50,14 +61,37 @@ describe Foo, focus: true do
 end
 ```
 
-The normal `rspec` command will *not* use this filter in case it is ever committed accidentally, so CI can catch any problems.
+The normal `rspec` command will *not* use this filter in case it is ever
+committed accidentally, so CI can catch any problems.
+
+## Releasing a new version
+
+The normal gem release cycle works using `rake release`.
+
+If you make changes to the docker image, you can release it using `rake
+docker:release`.
 
 ## Copyright & License
 
-Copyright © 2015 Hemnet Service HNS AB
+Copyright © 2015-2017 Hemnet Service HNS AB
+
+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:
 
-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 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.
 
-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.
+[api]: https://developer.wordpress.org/rest-api/
+[docs]: http://www.rubydoc.info/gems/wordpress_client/

data/Rakefile

@@ -1 +1,38 @@
 require "bundler/gem_tasks"
+require "yard"
+require "wordpress_client/version"
+
+YARD::Rake::YardocTask.new
+
+namespace :docker do
+  DOCKER_DIR = File.expand_path("../spec/docker", __FILE__).freeze
+  IMAGE_NAME = "hemnet/wordpress_client_test".freeze
+  DEV_IMAGE = [IMAGE_NAME, "dev"].join(":").freeze
+
+  desc "Build the docker image"
+  task :build do
+    sh "docker", "build", "-t", DEV_IMAGE, DOCKER_DIR
+  end
+
+  desc "Release current dev build"
+  task release: :build do
+    version = prompt "Which version do you want to release"
+    raise "Invalid version string" unless version =~ /\A[\d.]+\z/
+
+    latest = prompt "Do you want this to be the :latest release? [Y/n]"
+    latest = (latest.empty? || latest.casecmp("y").zero?)
+
+    sh "docker", "tag", DEV_IMAGE, "#{IMAGE_NAME}:#{version}"
+    sh "docker", "push", "#{IMAGE_NAME}:#{version}"
+
+    if latest
+      sh "docker", "tag", DEV_IMAGE, "#{IMAGE_NAME}:latest"
+      sh "docker", "push", "#{IMAGE_NAME}:latest"
+    end
+  end
+end
+
+def prompt(message)
+  print "#{message} > "
+  STDIN.gets.strip
+end

data/lib/wordpress_client/category.rb

@@ -1,4 +1,6 @@
 module WordpressClient
+  # Represents a category from Wordpress.
+  # @see Term
   class Category < Term
   end
 end

data/lib/wordpress_client/client.rb

@@ -4,108 +4,267 @@ module WordpressClient
       @connection = connection
     end
 
-    def posts(per_page: 10, page: 1, category_slug: nil, tag_slug: nil)
-      filter = {}
-      filter[:category_name] = category_slug if category_slug
-      filter[:tag] = tag_slug if tag_slug
+    # @!group Posts
+
+    # Find {Post Posts} matching given parameters.
+    #
+    # @example Finding 5 posts
+    #   posts = client.posts(per_page: 5)
+    #
+    # @param page [Fixnum] Current page for pagination. Defaults to 1.
+    # @param per_page [Fixnum] Posts per page. Defaults to 10.
+    #
+    # @return {PaginatedCollection[Post]} Paginated collection of the found posts.
+    def posts(per_page: 10, page: 1)
       connection.get_multiple(
-        Post, "posts", per_page: per_page, page: page, _embed: nil, context: "edit", filter: filter
+        Post,
+        "posts",
+        per_page: per_page,
+        page: page,
+        _embed: nil,
       )
     end
 
-    def categories(per_page: 10, page: 1)
-      connection.get_multiple(Category, "terms/category", page: page, per_page: per_page)
+    # Find the {Post} with the given ID, or raises an error if not found.
+    #
+    # @return {Post}
+    # @raise {NotFoundError}
+    # @raise {subclasses of Error} on other unexpected errors
+    def find_post(id)
+      connection.get(Post, "posts/#{id.to_i}", _embed: nil)
     end
 
-    def tags(per_page: 10, page: 1)
-      connection.get_multiple(Tag, "terms/tag", page: page, per_page: per_page)
+    # Create a new {Post} with the given attributes in Wordpress and return it.
+    #
+    # In addition to {http://v2.wp-api.org/reference/posts/ the accepted
+    # parameters of the API}, this method also takes the following keys:
+    # * +:meta+
+    # * +:category_ids+
+    # * +:tag_ids+
+    #
+    # @see http://v2.wp-api.org/reference/posts/ List of accepted parameters
+    # @param attributes [Hash<Symbol,Object>] attribute list, containing
+    #                   accepted parameters or the custom parameters listed
+    #                   above.
+    # @option attributes [Hash<String,String>] meta Hash of meta values.
+    # @option attributes [Array<Fixnum>] category_ids List of category IDs the
+    #                                    Post should belong to.
+    # @option attributes [Array<Fixnum>] tag_ids List of tag IDs the Post
+    #                                    should have.
+    #
+    # @return {Post}
+    # @raise {ValidationError}
+    # @raise {subclasses of Error} on other unexpected errors
+    def create_post(attributes)
+      connection.create(Post, "posts", attributes, redirect_params: {_embed: nil})
     end
 
-    def media(per_page: 10, page: 1)
-      connection.get_multiple(Media, "media", page: page, per_page: per_page)
+    # Update the {Post} with the given id, setting the supplied attributes in
+    # Wordpress and returning an updated Post.
+    #
+    # In addition to {http://v2.wp-api.org/reference/posts/ the accepted
+    # parameters of the API}, this method also takes the following keys:
+    # * +:meta+
+    # * +:category_ids+
+    # * +:tag_ids+
+    #
+    # @example Changing the title of a Post
+    #   new_post = client.update_post(post.id, title: "A better title")
+    #   new_post.title_html #=> "A better title"
+    #
+    # @see http://v2.wp-api.org/reference/posts/ List of accepted parameters
+    # @param id [Fixnum] ID of the post to update.
+    # @param attributes [Hash<Symbol,Object>] attribute list, containing
+    #                   accepted parameters or the custom parameters listed
+    #                   above.
+    # @option attributes [Hash<String,String>] meta Hash of meta values.
+    # @option attributes [Array<Fixnum>] category_ids List of category IDs the
+    #                                    Post should belong to.
+    # @option attributes [Array<Fixnum>] tag_ids List of tag IDs the Post
+    #                                    should have.
+    #
+    # @return {Post}
+    # @raise {NotFoundError}
+    # @raise {ValidationError}
+    # @raise {subclasses of Error} on other unexpected errors
+    def update_post(id, attributes)
+      connection.put(Post, "posts/#{id.to_i}", attributes)
     end
 
-    def find_post(id)
-      connection.get(Post, "posts/#{id.to_i}", _embed: nil, context: "edit")
+    # Deletes the {Post} with the given ID.
+    #
+    # @param id [Fixnum] The {Post} ID.
+    # @param force [Boolean] When +false+, the Post will be put in the "Trash"
+    #        of Wordpress. +true+ causes the Post to be irrevocably deleted.
+    #
+    # @return true always
+    def delete_post(id, force: false)
+      connection.delete("posts/#{id.to_i}", {"force" => force})
     end
 
-    def find_by_slug(slug)
-      posts = connection.get_multiple(
-        Post, "posts", per_page: 1, page: 1, filter: {name: slug}, _embed: nil
-      )
-      if posts.size > 0
-        posts.first
-      else
-        raise NotFoundError, "Could not find post with slug #{slug.to_s.inspect}"
-      end
+    # @!group Categories
+
+    # Find {Category Categories} in the Wordpress install.
+    #
+    # @return {PaginatedCollection[Category]}
+    def categories(per_page: 10, page: 1)
+      connection.get_multiple(Category, "categories", page: page, per_page: per_page)
     end
 
+    # Find {Category} with the given ID.
+    #
+    # @return {Category}
+    # @raise {NotFoundError}
+    # @raise {subclasses of Error} on other unexpected errors
     def find_category(id)
-      connection.get(Category, "terms/category/#{id.to_i}")
+      connection.get(Category, "categories/#{id.to_i}")
     end
 
-    def find_tag(id)
-      connection.get(Tag, "terms/tag/#{id.to_i}")
+    # Create a new {Category} with the given attributes.
+    #
+    # @see http://v2.wp-api.org/reference/taxonomies/ List of accepted parameters
+    # @param attributes [Hash<Symbol,Object>] attribute list, containing
+    #                   parameters accepted by the API.
+    # @option attributes [String] name Name of the category (required).
+    # @option attributes [String] slug Slug of the category (optional).
+    # @option attributes [String] description Description of the category (optional).
+    #
+    # @return {Category} the new Category
+    # @raise {ValidationError}
+    # @raise {subclasses of Error} on other unexpected errors
+    def create_category(attributes)
+      connection.create(Category, "categories", attributes)
     end
 
-    def find_media(id)
-      connection.get(Media, "media/#{id.to_i}")
+    # Update the {Category} with the given id, setting the supplied attributes.
+    #
+    # @see http://v2.wp-api.org/reference/taxonomies/ List of accepted parameters
+    # @param attributes [Hash<Symbol,Object>] attribute list, containing
+    #                   parameters accepted by the API.
+    # @option attributes [String] name Name of the category.
+    # @option attributes [String] slug Slug of the category.
+    # @option attributes [String] description Description of the category.
+    #
+    # @return {Category} the updated Category
+    # @raise {NotFoundError}
+    # @raise {ValidationError}
+    # @raise {subclasses of Error} on other unexpected errors
+    def update_category(id, attributes)
+      connection.put(Category, "categories/#{id.to_i}", attributes)
     end
 
-    def create_post(attributes)
-      post = connection.create(Post, "posts", attributes, redirect_params: {_embed: nil})
-
-      changes = 0
-      changes += assign_meta(post, attributes[:meta])
-      changes += assign_categories(post, attributes[:category_ids])
-      changes += assign_tags(post, attributes[:tag_ids])
+    # @!group Tags
 
-      if changes > 0
-        find_post(post.id)
-      else
-        post
-      end
+    # Find {Tag Tags} in the Wordpress install.
+    #
+    # @return {PaginatedCollection[Tag]}
+    def tags(per_page: 10, page: 1)
+      connection.get_multiple(Tag, "tags", page: page, per_page: per_page)
     end
 
-    def create_category(attributes)
-      connection.create(Category, "terms/category", attributes)
+    # Find {Tag} with the given ID.
+    #
+    # @return {Tag}
+    # @raise {NotFoundError}
+    # @raise {subclasses of Error} on other unexpected errors
+    def find_tag(id)
+      connection.get(Tag, "tags/#{id.to_i}")
     end
 
+    # Create a new {Tag} with the given attributes.
+    #
+    # @see http://v2.wp-api.org/reference/taxonomies/ List of accepted parameters
+    # @param attributes [Hash<Symbol,Object>] attribute list, containing
+    #                   parameters accepted by the API.
+    # @option attributes [String] name Name of the tag (required).
+    # @option attributes [String] slug Slug of the tag (optional).
+    # @option attributes [String] description Description of the tag (optional).
+    #
+    # @return {Tag} the new Tag
+    # @raise {ValidationError}
+    # @raise {subclasses of Error} on other unexpected errors
     def create_tag(attributes)
-      connection.create(Tag, "terms/tag", attributes)
+      connection.create(Tag, "tags", attributes)
     end
 
-    def update_post(id, attributes)
-      post = connection.patch(Post, "posts/#{id.to_i}?_embed", attributes)
-
-      changes = 0
-      changes += assign_meta(post, attributes[:meta])
-      changes += assign_categories(post, attributes[:category_ids])
-      changes += assign_tags(post, attributes[:tag_ids])
-
-      if changes > 0
-        find_post(post.id)
-      else
-        post
-      end
+    # Update the {Tag} with the given id, setting the supplied attributes.
+    #
+    # @see http://v2.wp-api.org/reference/taxonomies/ List of accepted parameters
+    # @param attributes [Hash<Symbol,Object>] attribute list, containing
+    #                   parameters accepted by the API.
+    # @option attributes [String] name Name of the tag.
+    # @option attributes [String] slug Slug of the tag.
+    # @option attributes [String] description Description of the tag.
+    #
+    # @return {Tag} the updated Tag
+    # @raise {NotFoundError}
+    # @raise {ValidationError}
+    # @raise {subclasses of Error} on other unexpected errors
+    def update_tag(id, attributes)
+      connection.put(Tag, "tags/#{id.to_i}", attributes)
     end
 
-    def update_category(id, attributes)
-      connection.patch(Category, "terms/category/#{id.to_i}", attributes)
-    end
+    # @!group Media
 
-    def update_tag(id, attributes)
-      connection.patch(Tag, "terms/tag/#{id.to_i}", attributes)
+    # Find {Media} in the Wordpress install.
+    #
+    # @return {PaginatedCollection[Media]}
+    def media(per_page: 10, page: 1)
+      connection.get_multiple(Media, "media", page: page, per_page: per_page)
     end
 
-    def update_media(id, attributes)
-      connection.patch(Media, "media/#{id.to_i}", attributes)
+    # Find {Media} with the given ID.
+    #
+    # @return {Media}
+    # @raise {NotFoundError}
+    # @raise {subclasses of Error} on other unexpected errors
+    def find_media(id)
+      connection.get(Media, "media/#{id.to_i}")
     end
 
+    # Create a new {Media} by uploading a IO stream.
+    #
+    # You need to provide both MIME type and filename for Wordpress to accept
+    # the file.
+    #
+    # @example Uploading a JPEG from a request
+    #   media = client.upload(
+    #     request.body_stream, filename: "foo.jpg", mime_type: "image/jpeg"
+    #   )
+    #
+    # @param io [IO-like object] IO stream (for example an open file) that will
+    #        be the body of the media.
+    # @param mime_type [String] the MIME type of the IO stream
+    # @param filename [String] the filename that Wordpress should see. Requires
+    #        a file extension to make Wordpress happy.
+    #
+    # @return {Media} the new Media
+    # @raise {ValidationError}
+    # @raise {subclasses of Error} on other unexpected errors
+    # @see #upload_file #upload_file - a shortcut for uploading files on disk
     def upload(io, mime_type:, filename:)
       connection.upload(Media, "media", io, mime_type: mime_type, filename: filename)
     end
 
+    # Create a new {Media} by uploading a file from disk.
+    #
+    # You need to provide MIME type for Wordpress to accept the file. The
+    # filename that Wordpress sees will automatically be derived from the
+    # passed path.
+    #
+    # @example Uploading a JPEG from disk
+    #   media = client.upload_file(
+    #     "assets/ocean.jpg", mime_type: "image/jpeg"
+    #   )
+    #
+    # @param filename [String] a path to a readable file.
+    # @param mime_type [String] the MIME type of the file.
+    #
+    # @return {Media} the new Media
+    # @raise {ValidationError}
+    # @raise {subclasses of Error} on other unexpected errors
+    # @see #upload #upload - for when you want to upload something that isn't a
+    #              file on disk, or need extra flexibility
     def upload_file(filename, mime_type:)
       path = filename.to_s
       File.open(path, 'r') do |file|
@@ -113,30 +272,27 @@ module WordpressClient
       end
     end
 
-    def delete_post(id, force: false)
-      connection.delete("posts/#{id.to_i}", {"force" => force})
+    # Update the {Media} with the given id, setting the supplied attributes.
+    #
+    # @see http://v2.wp-api.org/reference/media/ List of accepted parameters
+    # @param attributes [Hash<Symbol,Object>] attribute list, containing
+    #                   parameters accepted by the API.
+    #
+    # @return {Media} The updated Media
+    # @raise {NotFoundError}
+    # @raise {ValidationError}
+    # @raise {subclasses of Error} on other unexpected errors
+    def update_media(id, attributes)
+      connection.put(Media, "media/#{id.to_i}", attributes)
     end
 
+    # @!endgroup
+
     def inspect
       "#<WordpressClient::Client #{connection.inspect}>"
     end
 
     private
     attr_reader :connection
-
-    def assign_categories(post, ids)
-      return 0 unless ids
-      ReplaceTerms.apply_categories(connection, post, ids)
-    end
-
-    def assign_tags(post, ids)
-      return 0 unless ids
-      ReplaceTerms.apply_tags(connection, post, ids)
-    end
-
-    def assign_meta(post, meta)
-      return 0 unless meta
-      ReplaceMetadata.apply(connection, post, meta)
-    end
   end
 end

data/lib/wordpress_client/connection.rb

@@ -2,6 +2,7 @@ require "faraday"
 require "json"
 
 module WordpressClient
+  # @private
   class Connection
     attr_reader :url, :username
 
@@ -49,14 +50,14 @@ module WordpressClient
       true
     end
 
-    def patch(model, path, attributes)
+    def put(model, path, attributes)
       model.parse(
-        parse_json_response(send_json(path, attributes, method: :patch))
+        parse_json_response(send_json(path, attributes, method: :put))
       )
     end
 
-    def patch_without_response(path, attributes)
-      handle_status_code(send_json(path, attributes, method: :patch))
+    def put_without_response(path, attributes)
+      handle_status_code(send_json(path, attributes, method: :put))
       true
     end
 
@@ -65,9 +66,7 @@ module WordpressClient
       response = post_data(path, body, {
         "Content-Length" => body.size.to_s,
         "Content-Type" => mime_type,
-        # WP API does not parse normal Content-Disposition and instead ops to using their own format
-        # https://github.com/WP-API/WP-API/issues/1744
-        "Content-Disposition" => "filename=#{filename || "unnamed"}",
+        "Content-Disposition" => 'attachment; filename="' + (filename || "unnamed") + '"',
       })
 
       if response.status == 201 # Created
@@ -88,7 +87,7 @@ module WordpressClient
     end
 
     def setup_network_connection
-      Faraday.new(url: "#{url}/wp/v2") do |conn|
+      Faraday.new(url: File.join(url, "wp/v2")) do |conn|
         conn.request :basic_auth, username, @password
         conn.adapter :net_http
       end
@@ -111,8 +110,9 @@ module WordpressClient
     def get_json_and_response(path, params = {})
       response = net.get(path, params)
       [parse_json_response(response), response]
-    rescue Faraday::TimeoutError
-      raise TimeoutError
+    rescue Faraday::ConnectionFailed => error
+      raise TimeoutError if error.cause.class == Net::OpenTimeout
+      raise
     end
 
     def send_json(path, data, method: :post)

data/lib/wordpress_client/errors.rb

@@ -1,10 +1,45 @@
 module WordpressClient
-  Error = Class.new(::StandardError)
+  # Base class for all errors emitted from this gem. Rescue this in order to
+  # catch everything.
+  #
+  # See the list of subclasses for more specific error types.
+  class Error < ::StandardError; end
 
-  UnauthorizedError = Class.new(Error)
+  # Raised when the clients attempt to do something that the user isn't
+  # authorized to do.
+  #
+  # This could happen if you try to delete a post and the user only has
+  # read-only access, for example.
+  # It would also happen if you provide bad authentication details.
+  #
+  # @see Error
+  class UnauthorizedError < Error; end
 
-  TimeoutError = Class.new(Error)
-  ServerError = Class.new(Error)
-  NotFoundError = Class.new(Error)
-  ValidationError = Class.new(Error)
+  # Raised when a request times out.
+  #
+  # @see Error
+  class TimeoutError < Error; end
+
+  # Raised when the server had an error, or when the server returned something
+  # unexpected, despite saying everything went okay. It's the most generic
+  # "Something went wrong with the request" error.
+  #
+  # @see Error
+  class ServerError < Error; end
+
+  # Raised when trying to find a resource that doesn't exist. It will also
+  # happen when you try to update a resource that doesn't exist.
+  #
+  # Lack of authorization can also mask actual resources so it appears that
+  # they don't exist.
+  #
+  # @see Error
+  class NotFoundError < Error; end
+
+  # Raised when the server rejects the body of a request. The error message
+  # will often include information about why the body was rejected, but it is
+  # not guaranteed.
+  #
+  # @see Error
+  class ValidationError < Error; end
 end