pinterest-ruby 1.0.0

data/lib/pinterest/endpoints/pins.rb

@@ -0,0 +1,187 @@
+#
+# This file is part of the pinterest-ruby gem. Copyright (C) 2017 and above Shogun <shogun@cowtech.it>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Pinterest
+  module Endpoints
+    # Pins related endpoints.
+    module Pins
+      # Returns information about a pin.
+      #
+      # @param pin [Fixnum|String] The pin id.
+      # @param fields [Array] A list of fields to return.
+      # @return [Pinterest::User] A pin object.
+      def pin(pin, fields: nil)
+        # Validate the pin id
+        pin = validate_pin(pin)
+
+        # Ensure only valid fields are used
+        fields = ensure_pin_fields(fields)
+
+        # Perform the request and create the pin
+        data = perform_network_request(url: versioned_url("/pins/#{pin}/"), query: cleanup_params({fields: fields.join(",")})).body["data"]
+        ::Pinterest::Pin.create(data)
+      end
+
+      # Creates a new pin.
+      #
+      # @param board [String] The board path (username/id) or id.
+      # @param image [String] The image to pin.
+      # @param note [String] The note to attach to the pin.
+      # @param link [String] The link to attach to the pin.
+      # @param fields [Array] A list of fields to return.
+      # @return [Pinterest::User] The new created pin object.
+      def create_pin(board, image, note: nil, link: nil, fields: nil)
+        board = validate_board(board)
+
+        # Ensure only valid fields are used
+        fields = ensure_pin_fields(fields)
+
+        # Create the payload
+        payload = {note: note, board: board, link: link}
+
+        # Add the image - Try to detect whether is a URL or a path
+        payload.merge!(add_image(image))
+
+        # Perform the request and create the pin
+        data = perform_network_request(method: "POST", url: versioned_url("/pins/"), query: cleanup_params({fields: fields.join(",")}), body: payload)
+
+        ::Pinterest::Pin.create(data.body["data"])
+      end
+
+      # Edits a pin.
+      #
+      # @param pin [String] The pin id.
+      # @param board [String] The new board path (username/id) or id.
+      # @param note [String] The new note to attach to the pin.
+      # @param link [String] The new link to attach to the pin.
+      # @param fields [Array] A list of fields to return.
+      # @return [Pinterest::User] The updated pin object.
+      def edit_pin(pin, board: nil, note: nil, link: nil, fields: nil)
+        pin = validate_pin(pin)
+        board = validate_board(board) if board
+
+        # Ensure only valid fields are used
+        fields = ensure_pin_fields(fields)
+
+        # Create the payload
+        payload = cleanup_params({note: note, board: board, link: link})
+
+        # Perform the request and create the pin
+        data = perform_network_request(method: "PATCH", url: versioned_url("/pins/#{pin}/"), query: cleanup_params({fields: fields.join(",")}), body: payload)
+        ::Pinterest::Pin.create(data.body["data"])
+      end
+
+      # Deletes a pin.
+      #
+      # @param pin [String] The pin id.
+      # @return [Boolean] `true` if operation succeeded, `false` otherwise.
+      def delete_pin(pin)
+        # Validate the board id
+        pin = validate_pin(pin)
+
+        # Perform the request
+        perform_network_request(method: "DELETE", url: versioned_url("/pins/#{pin}/"))
+        true
+      end
+
+      # Returns the list of pins of the authenticated user.
+      #
+      # @param fields [Array] A list of fields to return.
+      # @param cursor [String] A cursor to paginate results, obtained by a previous call.
+      # @param limit [Fixnum] The maximum number of objects to return.
+      # @return [Pinterest::Collection] An collection of pin objects.
+      def pins(fields: nil, cursor: nil, limit: nil)
+        get_pins_collection("/me/pins/", nil, fields, cursor, limit)
+      end
+
+      # Search between of pins of the authenticated user.
+      #
+      # @param query [String] The query to perform.
+      # @param fields [Array] A list of fields to return.
+      # @param cursor [String] A cursor to paginate results, obtained by a previous call.
+      # @param limit [Fixnum] The maximum number of objects to return.
+      # @return [Pinterest::Collection] An collection of pin objects.
+      def search_my_pins(query = "", fields: nil, cursor: nil, limit: nil)
+        ensure_param(query, "You have to specify a query.")
+        get_pins_collection("/me/search/pins/", {query: query}, fields, cursor, limit)
+      end
+
+      # Returns the list of pins of a board of the authenticated user.
+      #
+      # @param board [Fixnum|String] The board path (username/id) or id.
+      # @param fields [Array] A list of fields to return.
+      # @param cursor [String] A cursor to paginate results, obtained by a previous call.
+      # @param limit [Fixnum] The maximum number of objects to return.
+      # @return [Pinterest::Collection] An collection of pin objects.
+      def board_pins(board, fields: nil, cursor: nil, limit: nil)
+        validate_board(board)
+        get_pins_collection("/boards/#{board}/pins/", nil, fields, cursor, limit)
+      end
+
+      # Returns the list of liked pins of the authenticated user.
+      #
+      # @param fields [Array] A list of fields to return.
+      # @param cursor [String] A cursor to paginate results, obtained by a previous call.
+      # @param limit [Fixnum] The maximum number of objects to return.
+      # @return [Pinterest::Collection] An collection of pin objects.
+      def likes(fields: nil, cursor: nil, limit: nil)
+        get_pins_collection("/me/likes/", nil, fields, cursor, limit)
+      end
+
+      private
+
+      # :nodoc:
+      def validate_pin(pin)
+        raise(ArgumentError, "You have to specify a pin or its id.") unless pin
+        pin = pin.id if pin.is_a?(::Pinterest::Pin)
+        pin
+      end
+
+      # :nodoc:
+      def get_pins_collection(path, params, fields, cursor, limit)
+        # Ensure only valid fields are used and merge params
+        fields = ensure_pin_fields(fields)
+        params ||= {}
+        params[:fields] = fields.join(",")
+
+        # Perform the request
+        data = perform_network_request(
+          url: versioned_url(path),
+          query: cleanup_params(params),
+          pagination: (cursor || limit), cursor: cursor, limit: limit
+        )
+
+        # Create the collection
+        ::Pinterest::Collection.new(data.body, cursor, limit) { |pin| ::Pinterest::Pin.create(pin) }
+      end
+
+      # :nodoc:
+      def ensure_pin_fields(fields = nil)
+        # Get fields and make sure only allowed fields are kept
+        fields = ensure_array(fields, ::Pinterest::Pin::FIELDS).map(&:to_s) & ::Pinterest::Pin::FIELDS
+
+        # Replace embedded fields
+        fields.map do |f|
+          case f
+          when "creator" then "creator(#{ensure_user_fields.join(",")})"
+          when "board" then "board(#{ensure_board_fields.join(",")})"
+          else f
+          end
+        end
+      end
+
+      # :nodoc:
+      def add_image(image)
+        raise(ArgumentError) if Addressable::URI.parse(image).scheme !~ /^http(s?)$/
+        {image_url: image}
+      rescue
+        type = FastImage.type(image)
+        raise(ArgumentError, "You have to specify a image URL or a valid image path.") unless type
+        type = type == :jpeg ? "jpg" : type.to_s
+        {image: Faraday::UploadIO.new(image, "image/#{type}")}
+      end
+    end
+  end
+end

data/lib/pinterest/endpoints/users.rb

@@ -0,0 +1,158 @@
+#
+# This file is part of the pinterest-ruby gem. Copyright (C) 2017 and above Shogun <shogun@cowtech.it>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Pinterest
+  module Endpoints
+    # Users related endpoints.
+    module Users
+      # Returns information about the authenticated user.
+      #
+      # @param fields [Array] A list of fields to return.
+      # @return [Pinterest::User] A user object.
+      def me(fields: nil)
+        fields = ensure_user_fields(fields)
+
+        # Perform request and create the user
+        data = perform_network_request(url: versioned_url("/me/"), query: cleanup_params({fields: fields.join(",")}))
+        ::Pinterest::User.create(data.body["data"])
+      end
+
+      # Returns information about a user.
+      #
+      # @param user [Fixnum|String] The username or user id.
+      # @param fields [Array] A list of fields to return.
+      # @return [Pinterest::User] A user object.
+      def user(user, fields: nil)
+        user = validate_user(user)
+        fields = ensure_user_fields(fields)
+
+        # Perform request and create the user
+        data = perform_network_request(url: versioned_url("/users/#{user}/"), query: cleanup_params({fields: fields.join(",")}))
+        ::Pinterest::User.create(data.body["data"])
+      end
+
+      # Returns the list of users who follow the authenticated user.
+      #
+      # @param fields [Array] A list of fields to return.
+      # @param cursor [String] A cursor to paginate results, obtained by a previous call.
+      # @param limit [Fixnum] The maximum number of objects to return.
+      # @return [Pinterest::Collection] An collection of user objects.
+      def followers(fields: nil, cursor: nil, limit: nil)
+        get_users_collection("/me/followers/", fields, cursor, limit)
+      end
+
+      # Returns the list of users followed by the authenticated user.
+      #
+      # @param fields [Array] A list of fields to return.
+      # @param cursor [String] A cursor to paginate results, obtained by a previous call.
+      # @param limit [Fixnum] The maximum number of objects to return.
+      # @return [Pinterest::Collection] An collection of user objects.
+      def following_users(fields: nil, cursor: nil, limit: nil)
+        get_users_collection("/me/following/users/", fields, cursor, limit)
+      end
+
+      # Follows a user.
+      #
+      # @param user [Fixnum|String] The username or user id.
+      # @return [Boolean] `true` if operation succeeded, `false` otherwise.
+      def follow_user(user)
+        # Validate the user id
+        user = validate_user(user)
+
+        # Perform the request
+        perform_network_request(method: "POST", body: {user: user}, url: versioned_url("/me/following/users/"))
+        true
+      end
+
+      # Stops following a user.
+      #
+      # @param user [Fixnum|String] The username or user id.
+      # @return [Boolean] `true` if operation succeeded, `false` otherwise.
+      def unfollow_user(user)
+        # Validate the user id
+        user = validate_user(user)
+
+        # Perform the request
+        perform_network_request(method: "DELETE", url: versioned_url("/me/following/users/#{user}/"))
+        true
+      end
+
+      # Returns the list of interests (topics) followed by the authenticated user.
+      #
+      # @param cursor [String] A cursor to paginate results, obtained by a previous call.
+      # @param limit [Fixnum] The maximum number of objects to return.
+      # @return [Pinterest::Collection] An collection of interest objects.
+      def interests(cursor: nil, limit: nil)
+        # Perform request
+        data = perform_network_request(
+          url: versioned_url("/me/following/interests/"),
+          pagination: true, cursor: cursor, limit: limit
+        )
+
+        # Create the collection
+        ::Pinterest::Collection.new(data.body, cursor, limit) { |interest| ::Pinterest::Interest.create(interest) }
+      end
+
+      # Starts following a interest.
+      #
+      # @param interest [Fixnum|String] The interest id.
+      # @return [Boolean] `true` if operation succeeded, `false` otherwise.
+      # NOTE: This is currently returning 405 on the platform. Review ASAP.
+      def follow_interest(interest)
+        # Validate the interest id
+        raise(ArgumentError, "You have to specify a interest or its id.") unless interest
+        interest = interest.id if interest.is_a?(::Pinterest::Interest)
+
+        # Perform the request
+        perform_network_request(method: "POST", query: {interest: interest}, url: versioned_url("/me/following/interests/"))
+      end
+
+      # Stops following a interest.
+      #
+      # @param interest [Fixnum|String] The interest id.
+      # @return [Boolean] `true` if operation succeeded, `false` otherwise.
+      # NOTE: This is currently returning 404 on the platform. Review ASAP.
+      def unfollow_interest(interest)
+        # Validate the interest id
+        raise(ArgumentError, "You have to specify a interest or its id.") unless interest
+        interest = interest.id if interest.is_a?(::Pinterest::Interest)
+
+        # Perform the request
+        perform_network_request(method: "DELETE", url: versioned_url("/me/following/interests/#{interest}/"))
+      end
+
+      private
+
+      # :nodoc:
+      def validate_user(user)
+        raise(ArgumentError, "You have to specify a user or its id.") unless user
+        user = user.id if user.is_a?(::Pinterest::User)
+        user
+      end
+
+      # :nodoc:
+      def get_users_collection(path, fields, cursor, limit)
+        # Ensure only valid fields are used
+        fields = ensure_user_fields(fields)
+
+        # Perform the request
+        data = perform_network_request(
+          url: versioned_url(path),
+          query: cleanup_params({fields: fields.join(",")}),
+          pagination: (cursor || limit), cursor: cursor, limit: limit
+        )
+
+        # Create the collection
+        ::Pinterest::Collection.new(data.body, cursor, limit) { |user| ::Pinterest::User.create(user) }
+      end
+
+      # :nodoc:
+      def ensure_user_fields(fields = nil)
+        # Get fields and make sure only allowed fields are kept
+        ensure_array(fields, ::Pinterest::User::FIELDS).map(&:to_s) & ::Pinterest::User::FIELDS
+      end
+    end
+  end
+end

data/lib/pinterest/errors.rb

@@ -0,0 +1,94 @@
+#
+# This file is part of the pinterest-ruby gem. Copyright (C) 2017 and above Shogun <shogun@cowtech.it>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Pinterest
+  # A list of errors returned by the client.
+  module Errors
+    # A dictionary that associates HTTP status codes to error classes.
+    CODES = {
+      400 => "BadRequestError",
+      401 => "AuthorizationError",
+      403 => "PermissionsError",
+      404 => "NotFoundError",
+      405 => "MethodNotAllowedError",
+      408 => "TimeoutError",
+      429 => "RateLimitError",
+      501 => "NotImplementedError"
+    }.freeze
+
+    # The base error.
+    class BaseError < RuntimeError
+      attr_accessor :code, :reason, :env
+
+      # Creates a new error.
+      #
+      # @param code [Fixnum] The error code.
+      # @param reason [String] The error message.
+      # @param env [Env] The environment.
+      def initialize(code, reason, env)
+        super("[#{code}] #{reason}")
+        @code = code
+        @reason = reason
+        @env = env
+      end
+    end
+
+    # Error raised in case of client errors.
+    class BadRequestError < BaseError
+    end
+
+    # Error raised in case of authorization errors.
+    class AuthorizationError < BaseError
+    end
+
+    # Error raised in case of permission errors.
+    class PermissionsError < BaseError
+    end
+
+    # Error raised in case of invalid requested entities.
+    class NotFoundError < BaseError
+    end
+
+    # Error raised in case of invalid requested actions.
+    class MethodNotAllowedError < BaseError
+    end
+
+    # Error raised in case of timeouts during network operations.
+    class TimeoutError < BaseError
+    end
+
+    # Error raised when rate-limited by Pinterest.
+    class RateLimitError < BaseError
+    end
+
+    # Error raised in case of unimplemented requested actions.
+    class NotImplementedError < BaseError
+    end
+
+    # Error raised in case of Pinterest server errors.
+    class ServerError < BaseError
+    end
+
+    # Creates a new error.
+    #
+    # @param response [Faraday::Response] The network response.
+    # @return [BaseError] A error object.
+    def self.create(response)
+      status = response.status
+      message = response.body["error"] || response.body["message"]
+
+      class_for_code(status).new(status, message, response.env)
+    end
+
+    # Get the class for a HTTP status code.
+    #
+    # @param status [Fixnum] The HTTP status code.
+    # @return [Class] The class.
+    def self.class_for_code(status)
+      klass = ::Pinterest::Errors::CODES.fetch(status, "ServerError")
+      Object.const_get("::Pinterest::Errors::#{klass}")
+    end
+  end
+end

data/lib/pinterest/models/board.rb

@@ -0,0 +1,34 @@
+#
+# This file is part of the pinterest-ruby gem. Copyright (C) 2017 and above Shogun <shogun@cowtech.it>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Pinterest
+  # A object representing a Pinterest board.
+  class Board < Entity
+    # The list of fields of the object.
+    FIELDS = ["id", "name", "url", "description", "creator", "created_at", "counts", "image"].freeze
+
+    attr_accessor(*FIELDS)
+
+    # Creates a new board object.
+    #
+    # @param data [Hash] The data of the new object. For a list of valid fields, see `Pinterest::Board::FIELDS`.
+    # @return [Pinterest::Board] The new board object.
+    def self.create(data)
+      data["created_at"] = Pinterest::Entity.parse_timestamp(data["created_at"]) if data["created_at"]
+      data["creator"] = Pinterest::User.create(data["creator"]) if data["creator"]
+      data["image"] = Pinterest::Image.new(data["image"]) if data["image"]
+
+      new(data)
+    end
+
+    # Serialize the object as a Hash that can be serialized as JSON.
+    #
+    # @param options [Hash] The options to use to serialize.
+    # @return [Hash] The serialized object.
+    def as_json(options = {})
+      super(::Pinterest::Board::FIELDS, options)
+    end
+  end
+end

data/lib/pinterest/models/entity.rb

@@ -0,0 +1,42 @@
+#
+# This file is part of the pinterest-ruby gem. Copyright (C) 2017 and above Shogun <shogun@cowtech.it>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Pinterest
+  # Base class for entity objects.
+  class Entity
+    # Parses a timestamps.
+    #
+    # @param timestamp [String] The string to parse.
+    # @return [DateTime] The parsed timestamp.
+    def self.parse_timestamp(timestamp)
+      return nil if !timestamp || timestamp.empty?
+      DateTime.parse(timestamp + "+00:00")
+    end
+
+    # Creates a new object.
+    #
+    # @param data [Hash] The data of the new object.
+    # @return [Pinterest::Board] The new object.
+    def initialize(data)
+      data.each do |field, value|
+        send("#{field}=", value) if respond_to?(field)
+      end
+    end
+
+    # Serialize the object as a Hash that can be serialized as JSON.
+    #
+    # @param options [Hash] The options to use to serialize.
+    # @return [Hash] The serialized object.
+    def as_json(fields, options = {})
+      fields.reduce({}) do |accu, field|
+        value = send(field)
+        value = value.as_json(options) if value.respond_to?(:as_json)
+
+        accu[field.to_sym] = value
+        accu
+      end
+    end
+  end
+end

data/lib/pinterest/models/image.rb

@@ -0,0 +1,49 @@
+#
+# This file is part of the pinterest-ruby gem. Copyright (C) 2017 and above Shogun <shogun@cowtech.it>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Pinterest
+  # A object representing a Pinterest image.
+  class Image
+    # Creates a new image object.
+    #
+    # @param data [Hash] The data of the new object.
+    # @return [Pinterest::Board] The new board object.
+    def initialize(data)
+      @data = data
+    end
+
+    # Returns the possible versions of a image.
+    #
+    # @return [Array] A list of possible version of a image.
+    def versions
+      @data.keys
+    end
+
+    # Returns the size of a version of the image.
+    #
+    # @param version [String] The version to inspect.
+    # @return [Hash] A hash with the `:width` and `:height` keys.
+    def size(version)
+      data = @data.fetch(version.to_s)
+      {width: data["width"], height: data["height"]}
+    end
+
+    # Returns the URL of a version of the image.
+    #
+    # @param version [String] The version to inspect.
+    # @return [String] The version URL.
+    def url(version)
+      @data.fetch(version.to_s)["url"]
+    end
+
+    # Serialize the object as a Hash that can be serialized as JSON.
+    #
+    # @param _ [Hash] The options to use to serialize.
+    # @return [Hash] The serialized object.
+    def as_json(_ = {})
+      @data
+    end
+  end
+end

data/lib/pinterest/models/interest.rb

@@ -0,0 +1,30 @@
+#
+# This file is part of the pinterest-ruby gem. Copyright (C) 2017 and above Shogun <shogun@cowtech.it>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Pinterest
+  # A object representing a Pinterest interest (topic).
+  class Interest < Entity
+    # The list of fields of the object.
+    FIELDS = ["id", "name"].freeze
+
+    attr_accessor(*FIELDS)
+
+    # Creates a new interest (topic) object.
+    #
+    # @param data [Hash] The data of the new object. For a list of valid fields, see `Pinterest::Interest::FIELDS`.
+    # @return [Pinterest::Board] The new interest object.
+    def self.create(data)
+      new(data)
+    end
+
+    # Serialize the object as a Hash that can be serialized as JSON.
+    #
+    # @param options [Hash] The options to use to serialize.
+    # @return [Hash] The serialized object.
+    def as_json(options = {})
+      super(::Pinterest::Interest::FIELDS, options)
+    end
+  end
+end

data/lib/pinterest/models/pin.rb

@@ -0,0 +1,43 @@
+#
+# This file is part of the pinterest-ruby gem. Copyright (C) 2017 and above Shogun <shogun@cowtech.it>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Pinterest
+  # A object representing a Pinterest pin.
+  class Pin < Entity
+    # The list of fields of the object.
+    FIELDS = ["id", "link", "url", "creator", "board", "created_at", "note", "color", "counts", "media", "attribution", "image"].freeze
+
+    attr_accessor(*FIELDS)
+
+    # Creates a new pin object.
+    #
+    # @param data [Hash] The data of the new object. For a list of valid fields, see `Pinterest::Pin::FIELDS`.
+    # @return [Pinterest::Board] The new pin object.
+    def self.create(data)
+      data["created_at"] = Pinterest::Entity.parse_timestamp(data["created_at"]) if data["created_at"]
+      data = create_relationships(data)
+      new(data)
+    end
+
+    # Converts the relationships (user, board, images) of the pin to a gem object.
+    #
+    # @param data [Hash] The raw data.
+    # @return [Hash] The input data where relationships are gem objects.
+    def self.create_relationships(data)
+      data["creator"] = Pinterest::User.create(data["creator"]) if data["creator"]
+      data["board"] = Pinterest::Board.create(data["board"]) if data["board"]
+      data["image"] = Pinterest::Image.new(data["image"]) if data["image"]
+      data
+    end
+
+    # Serialize the object as a Hash that can be serialized as JSON.
+    #
+    # @param options [Hash] The options to use to serialize.
+    # @return [Hash] The serialized object.
+    def as_json(options = {})
+      super(::Pinterest::Pin::FIELDS, options)
+    end
+  end
+end

data/lib/pinterest/models/user.rb

@@ -0,0 +1,33 @@
+#
+# This file is part of the pinterest-ruby gem. Copyright (C) 2017 and above Shogun <shogun@cowtech.it>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Pinterest
+  # A object representing a Pinterest user.
+  class User < Entity
+    # The list of fields of the object.
+    FIELDS = ["id", "username", "first_name", "last_name", "bio", "created_at", "counts", "image"].freeze
+
+    attr_accessor(*FIELDS)
+
+    # Creates a new user object.
+    #
+    # @param data [Hash] The data of the new object. For a list of valid fields, see `Pinterest::User::FIELDS`.
+    # @return [Pinterest::Board] The new user object.
+    def self.create(data)
+      data["created_at"] = Pinterest::Entity.parse_timestamp(data["created_at"]) if data["created_at"]
+      data["image"] = Pinterest::Image.new(data["image"]) if data["image"]
+
+      new(data)
+    end
+
+    # Serialize the object as a Hash that can be serialized as JSON.
+    #
+    # @param options [Hash] The options to use to serialize.
+    # @return [Hash] The serialized object.
+    def as_json(options = {})
+      super(::Pinterest::User::FIELDS, options)
+    end
+  end
+end