RubyGems - pinterest-ruby - Versions diffs - 1.0.0 - Mend

pinterest-ruby 1.0.0

Files changed (150) hide show

data/docs/top-level-namespace.html ADDED Viewed

@@ -0,0 +1,110 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  Top Level Namespace
+    &mdash; Documentation by YARD 0.9.7
+</title>
+  <link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />
+  <link rel="stylesheet" href="css/common.css" type="text/css" charset="utf-8" />
+<script type="text/javascript" charset="utf-8">
+  pathId = "";
+  relpath = '';
+</script>
+  <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
+  <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
+  </head>
+  <body>
+    <div class="nav_wrap">
+      <iframe id="nav" src="class_list.html?1"></iframe>
+      <div id="resizer"></div>
+    </div>
+    <div id="main" tabindex="-1">
+      <div id="header">
+        <div id="menu">
+    <a href="_index.html">Index</a> &raquo;
+    <span class="title">Top Level Namespace</span>
+</div>
+        <div id="search">
+    <a class="full_list_link" id="class_list_link"
+        href="class_list.html">
+        <svg width="24" height="24">
+          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
+        </svg>
+    </a>
+</div>
+        <div class="clear"></div>
+      </div>
+      <div id="content"><h1>Top Level Namespace
+</h1>
+<div class="box_info">
+</div>
+<h2>Defined Under Namespace</h2>
+<p class="children">
+      <strong class="modules">Modules:</strong> <span class='object_link'><a href="FaradayMiddleware.html" title="FaradayMiddleware (module)">FaradayMiddleware</a></span>, <span class='object_link'><a href="Pinterest.html" title="Pinterest (module)">Pinterest</a></span>
+</p>
+</div>
+      <div id="footer">
+  Generated on Thu Jan 12 16:28:12 2017 by
+  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.7 (ruby-2.3.0).
+</div>
+    </div>
+  </body>
+</html>

data/lib/pinterest/client.rb ADDED Viewed

@@ -0,0 +1,146 @@
+#
+# 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 Pinterest API client.
+  #
+  # @attribute access_token
+  #   @return [String] The access token.
+  # @attribute client_id [String]
+  #   @return The client id.
+  # @attribute client_secret [String]
+  #   @return The client secret.
+  # @attribute verbose [Boolean]
+  #   @return If log requests.
+  # @attribute connection_setup [Proc]
+  #   @return Additional code to execute on the connection object.
+  class Client
+    # The Pinterest API Root URL.
+    API_URL = "https://api.pinterest.com".freeze
+    # The Pinterest API version.
+    API_VERSION = "v1".freeze
+    # The allowed authorization scopes.
+    SCOPES = ["read_public", "write_public", "read_relationships", "write_relationships"].freeze
+    # The maximum number of results to return by default.
+    DEFAULT_LIMIT = 50
+    attr_accessor :client_id, :client_secret, :access_token, :verbose, :connection
+    # Creates a new client.
+    #
+    # @param access_token [String] The access token.
+    # @param client_id [String] The client id.
+    # @param client_secret [String] The client secret.
+    # @param verbose [Boolean] If log requests.
+    # @param connection_setup [Proc] Additional code to execute on the connection object.
+    def initialize(access_token: nil, client_id: nil, client_secret: nil, verbose: false, &connection_setup)
+      @client_id = client_id
+      @client_secret = client_secret
+      @access_token = access_token
+      @verbose = verbose
+      ensure_connection(connection_setup)
+    end
+    include Pinterest::Endpoints::Authentication
+    include Pinterest::Endpoints::Users
+    include Pinterest::Endpoints::Pins
+    include Pinterest::Endpoints::Boards
+    private
+    # :nodoc:
+    def ensure_connection(setup = nil)
+      setup ||= ->(c) { default_connection_setup(c) }
+      @connection ||= Faraday.new(url: ::Pinterest::Client::API_URL, &setup)
+    end
+    # :nodoc:
+    def ensure_array(subject, default = [])
+      subject = (subject ? [subject] : [default]).flatten unless subject.is_a?(Array)
+      subject
+    end
+    # :nodoc:
+    def ensure_param(param, error = nil)
+      valid = param && !param.to_s.strip.empty?
+      raise(ArgumentError, error) if error && !valid
+      valid
+    end
+    # :nodoc:
+    def default_connection_setup(c)
+      c.request(:multipart)
+      c.request(:url_encoded)
+      c.response(:safe_oj)
+      c.response(:logger) if verbose
+      c.use(FaradayMiddleware::FollowRedirects)
+      c.adapter(Faraday.default_adapter)
+    end
+    # :nodoc:
+    def cleanup_params(params)
+      params.reject { |_, v| !ensure_param(v) }
+    end
+    # :nodoc:
+    # rubocop:disable Metrics/ParameterLists
+    def perform_network_request(method: "GET", url: "/", query: {}, body: {}, headers: {}, authenticated: true, pagination: false, **args, &additional)
+      response = connection.send(method.downcase) do |request|
+        # Setup URL and headers
+        setup_headers(request, url, headers, query, authenticated)
+        # Handle pagination
+        handle_pagination(request, args) if pagination
+        # Add the body
+        request.body = body
+        # Run user callback
+        yield(request) if additional
+      end
+      # Perform the call
+      raise(::Pinterest::Errors.create(response)) unless response.success?
+      response
+    rescue Faraday::ParsingError => e
+      handle_network_error(e)
+    end
+    # :nodoc:
+    def handle_network_error(e)
+      code = e.response.status
+      message = /<h1>(.+?)<\/h1>/mi.match(e.response.body)
+      raise(::Pinterest::Errors.class_for_code(code).new(code, message ? message[1] : "Invalid response from the server.", e.response))
+    end
+    # :nodoc:
+    def handle_pagination(request, args)
+      limit = args[:limit].to_i
+      limit = DEFAULT_LIMIT if limit < 1
+      request.params[:cursor] = args[:cursor] if args[:cursor]
+      request.params[:limit] = limit
+    end
+    # :nodoc:
+    def setup_headers(request, url, headers, query, authenticated)
+      request.url(url)
+      request.headers["Authorization"] = "Bearer #{access_token}" if authenticated
+      request.headers.merge!(headers)
+      request.params.merge!(query)
+    end
+    # :nodoc:
+    def versioned_url(url)
+      "/#{::Pinterest::Client::API_VERSION}/#{url.gsub(/^\//, "")}"
+    end
+  end
+end

data/lib/pinterest/collection.rb ADDED Viewed

@@ -0,0 +1,97 @@
+#
+# 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 collection of objects, including pagination data.
+  #
+  # @attribute records
+  #   @return [Pinterest::Entity] A list of objects.
+  # @attribute limit
+  #   @return [Fixnum] The maximum number of results to get from Pinterest API.
+  # @attribute current_cursor
+  #   @return [String] The cursor to obtain the current page of results.
+  # @attribute next_cursor
+  #   @return [String] The cursor to obtain the next page of results.
+  class Collection
+    attr_reader :records, :limit, :current_cursor, :next_cursor
+    # Creates a new collection. This class is for internal use.
+    #
+    # @param raw_data [Hash] A raw response obtained by Pinterest API.
+    # @param cursor [String] The current cursor.
+    # @param limit [Fixnum] The maximum number of records to obtain from Pinterest API.
+    # @param record_creator [Proc] The code to trasform each raw record in a object.
+    def initialize(raw_data, cursor, limit, &record_creator)
+      raise(ArgumentError, "raw_data must be an Hash.") unless raw_data.is_a?(Hash)
+      record_creator ||= ->(record) { record }
+      @limit = limit
+      @current_cursor = cursor
+      @next_cursor = raw_data["page"]["cursor"] if raw_data["page"] && raw_data["page"]["cursor"]
+      @records = raw_data.fetch("data", []).map(&record_creator)
+    end
+    # Returns a object from the collection.
+    #
+    # @param index [Fixnum] The index to get.
+    def [](index)
+      records[index]
+    end
+    # Returns the size of the collection.
+    #
+    # @return [Fixnum] The size of the collection.
+    def size
+      records.count
+    end
+    alias_method :count, :size
+    alias_method :length, :size
+    # Returns the current page cursor.
+    #
+    # @return [String] The current page cursor.
+    def current_page
+      current_cursor
+    end
+    # Returns the next page cursor.
+    #
+    # @return [String] The next page cursor.
+    def next_page
+      next_cursor
+    end
+    # Checks if the collection is empty.
+    #
+    # @return [Boolean] `true` if the collection is empty, `false` otherwise.
+    def empty?
+      records.empty?
+    end
+    # Checks if the collection has a next page.
+    #
+    # @return [Boolean] `true` if the collection has a next page, `false` otherwise.
+    def next?
+      !next_cursor.nil?
+    end
+    alias_method :next_page?, :next?
+    alias_method :eof?, :next?
+    # Serialize the collection as a Hash that can be serialized as JSON.
+    #
+    # @param options [Hash] The options to use to serialize.
+    # @return [Hash] The serialized collection.
+    def as_json(options = {})
+      {
+        records: records.as_json(options),
+        limit: limit,
+        current_cursor: current_cursor,
+        next_cursor: next_cursor
+      }
+    end
+  end
+end

data/lib/pinterest/endpoints/authentication.rb ADDED Viewed

@@ -0,0 +1,99 @@
+#
+# 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
+  # Pinterest API endpoints.
+  module Endpoints
+    # Authentication related endpoints.
+    module Authentication
+      # Returns a state string needed for authorization by the Pinterest API.
+      #
+      # @return [String] The state.
+      def authorization_state
+        @state ||= SecureRandom.hex
+      end
+      # Returns the URL to start the authentication flow.
+      #
+      # @param callback_url [String] The callback where to redirect the browser when done.
+      # @param scopes [Array] The list of scopes to ask for. For a list of valid fields, see `Pinterest::Client::SCOPES`.
+      # @return [String] The authorization URL.
+      def authorization_url(callback_url = nil, scopes = nil)
+        ensure_param(client_id, "You must specify the client_id.")
+        ensure_param(callback_url, "You must specify the callback_url.")
+        validate_callback_url(callback_url)
+        # Create the query
+        query = cleanup_params({
+          response_type: "code", client_id: client_id.to_s, authorization_state: authorization_state, redirect_uri: callback_url,
+          scope: (ensure_array(scopes, ::Pinterest::Client::SCOPES) & ::Pinterest::Client::SCOPES).join(",") # Restrict to only valid scopes
+        })
+        # Create the URL
+        url = Addressable::URI.parse(::Pinterest::Client::API_URL + "/oauth")
+        url.query_values = query
+        url.to_s
+      end
+      # Fetches the access token.
+      #
+      # @param [String] authorization_token The authorization token.
+      # @return [String] The authentication token.
+      def fetch_access_token(authorization_token)
+        ensure_param(client_id, "You must specify the client_id.")
+        ensure_param(client_secret, "You must specify the client_secret.")
+        ensure_param(authorization_token, "You must specify the authorization_token.")
+        # Create parameters
+        query = cleanup_params({
+          client_id: client_id, client_secret: client_secret,
+          grant_type: "authorization_code", code: authorization_token
+        })
+        # Perform the request and then get the token
+        response = perform_network_request(method: :post, url: versioned_url("/oauth/token"), query: query)
+        @access_token = response.body["access_token"]
+      end
+      # Verifies the access token.
+      #
+      # @return [Hash] The access token informations.
+      def verify_access_token
+        ensure_param(client_id, "You must specify the client_id.")
+        ensure_param(access_token, "You must set the access token first.")
+        # Get the data
+        data = perform_network_request(url: versioned_url("/oauth/inspect"), authenticated: true).body["data"]
+        # Prepare for output
+        create_authentication(data)
+      end
+      private
+      # :nodoc:
+      def validate_callback_url(url)
+        valid =
+          begin
+            Addressable::URI.parse(url).scheme == "https"
+          rescue
+            false
+          end
+        raise(ArgumentError, "callback_url must be a valid HTTPS URL.") unless valid
+      end
+      # :nodoc:
+      def create_authentication(data)
+        {
+          created_at: ::Pinterest::Entity.parse_timestamp(data["issued_at"]),
+          scopes: data["scopes"],
+          user_id: data["user_id"].to_s,
+          application_id: data["app"]["id"].to_s
+        }
+      end
+    end
+  end
+end

data/lib/pinterest/endpoints/boards.rb ADDED Viewed

@@ -0,0 +1,193 @@
+#
+# 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
+    # Boards related endpoints.
+    module Boards
+      # Returns information about a board.
+      #
+      # @param board [String] The board path (username/id) or user id.
+      # @param fields [Array] A list of fields to return.
+      # @return [Pinterest::Board] A board object.
+      def board(board, fields: nil)
+        # Validate the board id
+        board = validate_board(board)
+        # Ensure only valid fields are used
+        fields = ensure_board_fields(fields)
+        # Perform the request and create the board
+        data = perform_network_request(url: versioned_url("/boards/#{board}/"), query: cleanup_params({fields: fields.join(",")})).body["data"]
+        ::Pinterest::Board.create(data)
+      end
+      # Returns the list of the boards of the authenticated user. Pagination is not supported by Pinterest API.
+      #
+      # @param fields [Array] A list of fields to return.
+      # @return [Pinterest::Collection] An collection of board objects.
+      def boards(fields: nil)
+        get_boards_collection("/me/boards/", nil, fields)
+      end
+      # Creates a new board.
+      #
+      # @param name [String] The board name.
+      # @param description [String] The board description.
+      # @param fields [Array] A list of fields to return.
+      # @return [Pinterest::Board] The created board object.
+      def create_board(name, description = "", fields: nil)
+        # Validate name
+        ensure_param(name, "You have to specify the board name.")
+        # Ensure only valid fields are used
+        fields = ensure_board_fields(fields)
+        # Create the board
+        data = perform_network_request(
+          method: "POST", url: versioned_url("/boards/"),
+          query: cleanup_params({fields: fields.join(",")}),
+          body: cleanup_params({name: name, description: description})
+        )
+        # Wrap in a object
+        ::Pinterest::Board.create(data.body["data"])
+      end
+      # Edits a board.
+      #
+      # @param board [Fixnum] The board id.
+      # @param name [String] The new board name.
+      # @param description [String] The new board description.
+      # @param fields [Array] A list of fields to return.
+      # @return [Pinterest::Board] The updated board object.
+      def edit_board(board, name: nil, description: nil, fields: nil)
+        # Validate the board id
+        raise(ArgumentError, "You have to specify a board or its id.") unless board
+        board = board.id if board.is_a?(::Pinterest::Board)
+        # Ensure only valid fields are used
+        fields = ensure_board_fields(fields)
+        # Create the board
+        data = perform_network_request(
+          method: "PATCH", url: versioned_url("/boards/#{board}/"),
+          query: cleanup_params(fields: fields.join(",")),
+          body: cleanup_params({name: name, description: description})
+        )
+        # Wrap in a object
+        ::Pinterest::Board.create(data.body["data"])
+      end
+      # Deletes a board.
+      #
+      # @param board [Fixnum] The board id.
+      # @return [Boolean] `true` if operation succeeded, `false` otherwise.
+      def delete_board(board)
+        # Validate the board id
+        board = validate_board(board)
+        # Perform the request
+        perform_network_request(method: "DELETE", url: versioned_url("/boards/#{board}/"))
+        true
+      end
+      # Search between of boards 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 board objects.
+      def search_my_boards(query, fields: nil, cursor: nil, limit: nil)
+        ensure_param(query, "You have to specify a query.")
+        get_boards_collection("/me/search/boards/", {query: query}, fields, cursor, limit)
+      end
+      # Returns the list of boards of suggested boards for 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 board objects.
+      def suggested_boards(fields: nil, cursor: nil, limit: nil)
+        get_boards_collection("/me/boards/suggested/", nil, fields, cursor, limit)
+      end
+      # Returns the list of boards 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 board objects.
+      def following_boards(fields: nil, cursor: nil, limit: nil)
+        get_boards_collection("/me/following/boards/", nil, fields, cursor, limit)
+      end
+      # Follows a board.
+      #
+      # @param board [String] The board id.
+      # @return [Boolean] `true` if operation succeeded, `false` otherwise.
+      def follow_board(board)
+        # Validate the board id
+        board = validate_board(board)
+        # Perform the request
+        perform_network_request(method: "POST", query: {board: board}, url: versioned_url("/me/following/boards/"))
+        true
+      end
+      # Stop following a board.
+      #
+      # @param board [String] The board id.
+      # @return [Boolean] `true` if operation succeeded, `false` otherwise.
+      def unfollow_board(board)
+        # Validate the board id
+        board = validate_board(board)
+        # Perform the request
+        perform_network_request(method: "DELETE", url: versioned_url("/me/following/boards/#{board}/"))
+        true
+      end
+      private
+      # :nodoc:
+      def get_boards_collection(path, params, fields, cursor = nil, limit = nil)
+        # Ensure only valid fields are used and merge params
+        fields = ensure_board_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) { |board| ::Pinterest::Board.create(board) }
+      end
+      # :nodoc:
+      def validate_board(board)
+        raise(ArgumentError, "You have to specify a board or its id.") unless board
+        board = board.id if board.is_a?(::Pinterest::Board)
+        board
+      end
+      # :nodoc:
+      def ensure_board_fields(fields = nil)
+        # Get fields and make sure only allowed fields are kept
+        fields = ensure_array(fields, ::Pinterest::Board::FIELDS).map(&:to_s) & ::Pinterest::Board::FIELDS
+        # Replace embedded fields
+        fields.map { |f| f == "creator" ? "creator(#{ensure_user_fields.join(",")})" : f }
+      end
+    end
+  end
+end