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

pinterest-ruby 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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