wordpress_client 0.0.1 → 2.0.1

data/lib/wordpress_client/media.rb

@@ -1,19 +1,58 @@
 module WordpressClient
+  # Represents a media record in Wordpress.
   class Media
     attr_accessor(
-      :id, :slug, :title_html, :description,
+      :id, :slug, :media_type, :title_html, :description, :alt_text,
       :date, :updated_at,
       :guid, :link, :media_details
     )
 
+    # @!attribute [r] media_type
+    #   @return [String] the type of the media
+    #   @example
+    #     media.media_type #=> "image"
+
+    # @!attribute [rw] title_html
+    #   @return [String] the title of the media, HTML escaped
+    #   @example
+    #     media.title_html #=> "Sunset — Painting by some person"
+
+    # @!attribute [rw] date
+    #   @return [Time, nil] the date of the media, in UTC if available
+
+    # @!attribute [rw] updated_at
+    #   @return [Time, nil] the modification date of the media, in UTC if available
+
+    # @!attribute [rw] guid
+    #   Returns the permalink/GUID – or +source_url+ – of the media.
+    #
+    #   Media that are embedded in posts have a +source_url+ attribute and no
+    #   +guid+, and stand-alone media has a +guid+ but no +source_url+. They
+    #   are both backed by the same data, so this method handles both cases,
+    #   and is aliased to both names.
+    #
+    #   @return [String] the permalink/GUID – or +source_url+ – of the media
+
+    # @!attribute [rw] media_details
+    #   Returns the media details if available.
+    #
+    #   Media details cannot be documented here. It's up to you to handle this
+    #   generic "payload" attribute the best way you can.
+    #
+    #   @return [Hash<String,Object>] the media details returned from the server
+
+    # @api private
     def self.parse(data)
       MediaParser.parse(data)
     end
 
+    # Creates a new instance, populating the fields with the passed values.
     def initialize(
       id: nil,
       slug: nil,
+      media_type: nil,
       title_html: nil,
+      alt_text: nil,
       description: nil,
       date: nil,
       updated_at: nil,
@@ -23,9 +62,11 @@ module WordpressClient
     )
       @id = id
       @slug = slug
+      @media_type = media_type
       @title_html = title_html
       @date = date
       @updated_at = updated_at
+      @alt_text = alt_text
       @description = description
       @guid = guid
       @link = link
@@ -33,5 +74,12 @@ module WordpressClient
     end
 
     alias source_url guid
+
+    # Returns the same +Media+ instance if it is an image, else +nil+.
+    def as_image
+      if media_type == "image"
+        self
+      end
+    end
   end
 end

data/lib/wordpress_client/media_parser.rb

@@ -1,4 +1,5 @@
 module WordpressClient
+  # @private
   class MediaParser
     include RestParser
 
@@ -26,8 +27,10 @@ module WordpressClient
 
     def assign_basic(media)
       media.id = data.fetch("id")
+      media.media_type = data.fetch("media_type")
       media.slug = data.fetch("slug")
       media.link = data.fetch("link")
+      media.alt_text = data.fetch("alt_text")
       media.description = data["description"]
       media.media_details = data["media_details"]
     end

data/lib/wordpress_client/paginated_collection.rb

@@ -1,9 +1,31 @@
 require "delegate"
 
 module WordpressClient
+  # Represents a paginated list of resources.
+  #
+  # @note This class has the full +Array+ interface by using
+  #       +DelegateClass(Array)+. Methods do not show up in the documentation
+  #       unless when manually documented.
   class PaginatedCollection < DelegateClass(Array)
+    # @!method size
+    #   @return [Fixnum] the number of records actually in this "page".
+    #   @see Array#size
+
     attr_reader :total, :current_page, :per_page
 
+    # @!attribute [r] total
+    #   @return [Fixnum] the total hits in the full collection.
+    #   @see #size #size is the size of the current "page".
+
+    # @!attribute [r] current_page
+    #   @return [Fixnum] the current page number, where +1+ is the first page.
+
+    # @!attribute [r] per_page
+    #   @return [Fixnum] the current page size setting, for example +30+.
+
+    # Create a new collection using the passed array +entries+.
+    #
+    # @param entries [Array] the original "page" array
     def initialize(entries, total:, current_page:, per_page:)
       super(entries)
       @total = total
@@ -11,12 +33,15 @@ module WordpressClient
       @per_page = per_page
     end
 
-    #
-    # Pagination methods. Fulfilling will_paginate protocol
-    #
+    # @!group will_paginate protocol
 
     alias total_entries total
 
+    # @note This method is used by +will_paginate+. By implementing this
+    #       interface, you can use a {PaginatedCollection} in place of a
+    #       +WillPaginate::Collection+ to render pagination details.
+    # @return [Fixnum] the total number of pages that can show the {#total}
+    #         entries with {#per_page} records per page. +0+ if no entries.
     def total_pages
       if total.zero? || per_page.zero?
         0
@@ -25,23 +50,53 @@ module WordpressClient
       end
     end
 
+    # @note This method is used by +will_paginate+. By implementing this
+    #       interface, you can use a {PaginatedCollection} in place of a
+    #       +WillPaginate::Collection+ to render pagination details.
+    # @return [Fixnum, nil] the next page number or +nil+ if on last page.
     def next_page
       if current_page < total_pages
         current_page + 1
       end
     end
 
+    # @note This method is used by +will_paginate+. By implementing this
+    #       interface, you can use a {PaginatedCollection} in place of a
+    #       +WillPaginate::Collection+ to render pagination details.
+    # @return [Fixnum, nil] the previous page number or +nil+ if on first page.
     def previous_page
       if current_page > 1
         current_page - 1
       end
     end
 
+    # @note This method is used by +will_paginate+. By implementing this
+    #       interface, you can use a {PaginatedCollection} in place of a
+    #       +WillPaginate::Collection+ to render pagination details.
+    # @return [Boolean] if the current page is out of bounds, e.g. less than 1
+    #                   or higher than {#total_pages}.
     def out_of_bounds?
       current_page < 1 || current_page > total_pages
     end
 
-    # will_paginate < 3.0 has this method
+    # @note This method is used by +will_paginate+. By implementing this
+    #       interface, you can use a {PaginatedCollection} in place of a
+    #       +WillPaginate::Collection+ to render pagination details.
+    #
+    # @note will_paginate < 3.0 has this method, but it's no longer present in
+    #       newer will_paginate.
+    #
+    # Returns the offset of the current page.
+    #
+    # @example First page offset
+    #   collection.per_page # => 20
+    #   collection.current_page # => 1
+    #   collection.offset #=> 0
+    # @example Later offset
+    #   collection.per_page # => 20
+    #   collection.current_page # => 3
+    #   collection.offset #=> 40
+    #
     def offset
       if current_page > 0
         (current_page - 1) * per_page
@@ -49,5 +104,7 @@ module WordpressClient
         0
       end
     end
+
+    # @!endgroup
   end
 end

data/lib/wordpress_client/post.rb

@@ -1,18 +1,68 @@
 require "time"
 
 module WordpressClient
+  # Represents a post in Wordpress.
+  #
+  # @see http://v2.wp-api.org/reference/posts/ API documentation for Post
   class Post
     attr_accessor(
       :id, :slug, :url, :guid, :status,
       :title_html, :excerpt_html, :content_html,
       :updated_at, :date,
-      :categories, :tags, :meta, :featured_image
+      :categories, :tags, :meta, :featured_media,
+      :tag_ids, :category_ids, :featured_media_id
     )
 
+    # @!attribute [rw] title_html
+    #   @return [String] the title of the media, HTML escaped
+    #   @example
+    #     post.title_html #=> "Fire & diamonds!"
+
+    # @!attribute [rw] date
+    #   @return [Time, nil] the date of the post, in UTC if available
+
+    # @!attribute [rw] updated_at
+    #   @return [Time, nil] the modification date of the post, in UTC if available
+
+    # @!attribute [rw] guid
+    #   @return [String] the permalink/GUID of the post for internal addressing
+    #   @see #url
+
+    # @!attribute [rw] url
+    #   @return [String] the URL (link) to the post
+
+    # @!attribute [rw] status
+    #   @return ["publish", "future", "draft", "pending", "private", nil] the
+    #           current status of the post, or +nil+ if undetermined
+
+    # @!attribute [rw] categories
+    #   @return [Array[Category]] the {Category Categories} the post belongs to.
+    #   @see Category
+
+    # @!attribute [rw] tags
+    #   @return [Array[Tag]] the {Tag Tags} the post belongs to.
+    #   @see Tag
+
+    # @!attribute [rw] featured_media
+    #   @return [Media, nil] the featured image, as an instance of {Media}
+    #   @see Media
+
+    # @!attribute [rw] meta
+    #   Returns the Post meta, as a +Hash+ of +String => String+.
+    #
+    #   @example
+    #     post.meta # => {"Mood" => "Happy", "reviewed_by" => "user:45"}
+    #
+    #   @return [Hash<String,String>] the post meta, as a Hash.
+    #   @see Category
+    #   @see Client#update_post
+
+    # @api private
     def self.parse(data)
       PostParser.parse(data)
     end
 
+    # Construct a new instance with the given attributes.
     def initialize(
       id: nil,
       slug: nil,
@@ -26,9 +76,10 @@ module WordpressClient
       date: nil,
       categories: [],
       tags: [],
-      featured_image: nil,
-      meta: {},
-      meta_ids: {}
+      category_ids: [],
+      tag_ids: [],
+      featured_media: nil,
+      meta: {}
     )
       @id = id
       @slug = slug
@@ -42,21 +93,17 @@ module WordpressClient
       @date = date
       @categories = categories
       @tags = tags
-      @featured_image = featured_image
+      @category_ids = category_ids
+      @tag_ids = tag_ids
+      @featured_media = featured_media
       @meta = meta
-      @meta_ids = meta_ids
-    end
-
-    def category_ids() categories.map(&:id) end
-
-    def tag_ids() tags.map(&:id) end
-
-    def featured_image_id
-      featured_image && featured_image.id
     end
 
-    def meta_id_for(key)
-      @meta_ids[key] || raise(ArgumentError, "Post does not have meta #{key.inspect}")
+    # Returns the featured media, if the featured media is an image.
+    def featured_image
+      if featured_media
+        featured_media.as_image
+      end
     end
   end
 end

data/lib/wordpress_client/post_parser.rb

@@ -1,4 +1,5 @@
 module WordpressClient
+  # @private
   class PostParser
     include RestParser
 
@@ -12,16 +13,13 @@ module WordpressClient
     end
 
     def to_post
-      meta, meta_ids = parse_metadata
-      post = Post.new(meta: meta, meta_ids: meta_ids)
-
+      post = Post.new
       assign_basic(post)
       assign_dates(post)
       assign_rendered(post)
       assign_categories(post)
       assign_tags(post)
-      assign_featured_image(post)
-
+      assign_featured_media(post)
       post
     end
 
@@ -33,6 +31,10 @@ module WordpressClient
       post.slug = data["slug"]
       post.url = data["link"]
       post.status = data["status"]
+      post.meta = data["meta"]
+      post.category_ids = data["categories"]
+      post.tag_ids = data["tags"]
+      post.featured_media_id = data["featured_media"]
     end
 
     def assign_dates(post)
@@ -59,34 +61,19 @@ module WordpressClient
       end
     end
 
-    def assign_featured_image(post)
-      featured_id = data["featured_image"]
+    def assign_featured_media(post)
+      featured_id = data["featured_media"]
       if featured_id
-        features = (embedded["https://api.w.org/featuredmedia"] || []).flatten
+        features = (embedded["wp:featuredmedia"] || []).flatten
         media = features.detect { |feature| feature["id"] == featured_id }
         if media
-          post.featured_image = Media.parse(media)
+          post.featured_media = Media.parse(media)
         end
       end
     end
 
-    def parse_metadata
-      embedded_metadata = (embedded["https://api.w.org/meta"] || []).flatten
-      validate_embedded_metadata(embedded_metadata)
-
-      meta = {}
-      meta_ids = {}
-
-      embedded_metadata.each do |entry|
-        meta[entry.fetch("key")] = entry.fetch("value")
-        meta_ids[entry.fetch("key")] = entry.fetch("id")
-      end
-
-      [meta, meta_ids]
-    end
-
     def embedded_terms(type)
-      term_collections = embedded["https://api.w.org/term"] || []
+      term_collections = embedded["wp:term"] || embedded["https://api.w.org/term"] || []
 
       # term_collections is an array of arrays with terms in them. We can see
       # the type of the "collection" by inspecting the first child's taxonomy.
@@ -95,19 +82,5 @@ module WordpressClient
       } || []
     end
 
-    def validate_embedded_metadata(embedded_metadata)
-      if embedded_metadata.size == 1 && embedded_metadata.first["code"]
-        error = embedded_metadata.first
-        case error["code"]
-        when "rest_forbidden"
-          raise UnauthorizedError, error.fetch(
-            "message", "You are not authorized to see meta for this post."
-          )
-        else
-          raise Error, "Could not retreive meta for this post: " \
-            "#{error["code"]} – #{error["message"]}"
-        end
-      end
-    end
   end
 end

data/lib/wordpress_client/rest_parser.rb

@@ -1,4 +1,8 @@
 module WordpressClient
+  # @private
+  #
+  # Module included in other classes that need to parse result bodies from the
+  # WP API.
   module RestParser
     private
     def rendered(name)

data/lib/wordpress_client/tag.rb

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

data/lib/wordpress_client/term.rb

@@ -1,7 +1,27 @@
 module WordpressClient
+  # @abstract Implement a subclass for the resource type.
+  #
+  # Implementation for the abstract "term" in Wordpress.
+  #
+  # @see Category
+  # @see Tag
   class Term
     attr_reader :id, :name_html, :slug
 
+    # @!attribute [r] id
+    #   @return [Fixnum] The ID of the resource in Wordpress.
+
+    # @!attribute [r] name_html
+    #   @return [String] The name of the resource, HTML encoded.
+    #   @example
+    #     term.name_html #=> "Father & Daughter stuff"
+
+    # @!attribute [r] slug
+    #   @return [String] The slug of the resource in Wordpress.
+
+    # @api private
+    #
+    # Parses a data structure from a WP API response body into this term type.
     def self.parse(data)
       new(
         id: data.fetch("id"),
@@ -16,6 +36,15 @@ module WordpressClient
       @slug = slug
     end
 
+    # @api private
+    # Compares another instance. All attributes in this list must be equal for
+    # the instances to be equal:
+    #
+    # * +id+
+    # * +name_html+
+    # * +slug+
+    #
+    # One must also not be a subclass of the other; they must be the exact same class.
     def ==(other)
       if other.is_a? Term
         other.class == self.class &&
@@ -27,6 +56,7 @@ module WordpressClient
       end
     end
 
+    # Shows a nice representation of the term type.
     def inspect
       "#<#{self.class} ##{id} #{name_html.inspect} (#{slug})>"
     end

data/lib/wordpress_client/version.rb

@@ -1,3 +1,7 @@
 module WordpressClient
-  VERSION = "0.0.1"
+  # Current version of the gem.
+  #
+  # @note This only applies if using a released version. A development build
+  #       would not correspond to this constant.
+  VERSION = "2.0.1".freeze
 end

data/lib/wordpress_client.rb

@@ -15,11 +15,27 @@ require "wordpress_client/post_parser"
 require "wordpress_client/media"
 require "wordpress_client/media_parser"
 
-require "wordpress_client/replace_terms"
-require "wordpress_client/replace_metadata"
-
 module WordpressClient
-  def self.new(*args)
-    Client.new(Connection.new(*args))
+  # Initialize a new client using the provided connection details.
+  # You need to provide authentication details, and the user must have +edit+
+  # permissions on the blog if you want to read Post Meta, or to modify
+  # anything.
+  #
+  # @example
+  #   client = WordpressClient.new(
+  #     url: "https://blog.example.com/wp-json",
+  #     username: "bot",
+  #     password: ENV.fetch("WORDPRESS_PASSWORD"),
+  #   )
+  #
+  # @see Client Client, for the methods available after creating the connection.
+  #
+  # @param url [String] The base URL to the wordpress install, including
+  #                     +/wp-json+.
+  # @param username [String] A valid username on the wordpress installation.
+  # @param password [String] The password for the provided user.
+  # @return {Client}
+  def self.new(url:, username:, password:)
+    Client.new(Connection.new(url: url, username: username, password: password))
   end
 end