unsplash_mango 1.0.0

data/lib/unsplash/configuration.rb

@@ -0,0 +1,29 @@
+module Unsplash # :nodoc:
+  class Configuration # :nodoc:
+    attr_accessor :application_access_key
+    attr_accessor :application_secret
+    attr_accessor :application_redirect_uri
+    attr_accessor :logger
+    attr_accessor :utm_source
+    attr_writer   :test
+
+    def initialize
+      @test = true
+      @logger = Logger.new(STDOUT)
+    end
+
+    def test?
+      !!@test
+    end
+
+    def application_id=(key)
+      logger.warn "Configuring application_id is deprecated. Use application_access_key."
+      self.application_access_key = key
+    end
+
+    def application_id
+      application_access_key
+    end
+
+  end
+end

data/lib/unsplash/connection.rb

@@ -0,0 +1,157 @@
+module Unsplash #:nodoc:
+
+  # HTTP connection to and communication with the Unsplash API.
+  class Connection
+    include HTTParty
+
+    # The version of the API being used if unspecified.
+    DEFAULT_VERSION  = "v1"
+
+    # Base URI for the Unsplash API..
+    DEFAULT_API_BASE_URI   = "https://api.unsplash.com"
+
+    # Base URI for Unsplash OAuth.
+    DEFAULT_OAUTH_BASE_URI = "https://unsplash.com"
+
+    # Create a Connection object.
+    # @param version [String] The Unsplash API version to use.
+    # @param api_base_uri [String] Base URI at which to make API calls.
+    # @param oauth_base_uri [String] Base URI for OAuth requests.
+    def initialize(version: DEFAULT_VERSION, api_base_uri: DEFAULT_API_BASE_URI, oauth_base_uri: DEFAULT_OAUTH_BASE_URI)
+      @application_access_key = Unsplash.configuration.application_access_key
+      @application_secret = Unsplash.configuration.application_secret
+      @api_version        = version
+      @api_base_uri       = api_base_uri
+
+      oauth_base_uri = oauth_base_uri
+      @oauth = ::OAuth2::Client.new(@application_access_key, @application_secret, site: oauth_base_uri) do |http|
+        http.request :multipart
+        http.request :url_encoded
+        http.adapter :net_http
+      end
+
+      Unsplash::Connection.base_uri @api_base_uri
+    end
+
+    # Get OAuth URL for user authentication and authorization.
+    # @param requested_scopes [Array] An array of permission scopes being requested.
+    # @return [String] The authorization URL.
+    def authorization_url(requested_scopes = ["public"])
+      @oauth.auth_code.authorize_url(redirect_uri: Unsplash.configuration.application_redirect_uri,
+                                     scope:        requested_scopes.join(" "))
+    end
+
+    # Generate an access token given an auth code received from Unsplash.
+    # This is used internally to authenticate and authorize future user actions.
+    # @param auth_code [String] The OAuth authentication code from Unsplash.
+    def authorize!(auth_code)
+      @oauth_token = @oauth.auth_code.get_token(auth_code, redirect_uri: Unsplash.configuration.application_redirect_uri)
+      # TODO check if it succeeded
+    end
+
+    # Extract hash with OAuth token attributes.  Extracted token attributes can
+    # be used with create_and_assign_token to prevent the need for
+    # reauthorization.
+    # @return [Hash, nil] @oauth_token converted to a hash.
+    def extract_token
+      @oauth_token.to_hash if @oauth_token
+    end
+
+    # Create and assign new access token from extracted token.  To be used with
+    # extract_token to reauthorize app without api call.
+    # @param token_extract [Hash] OAuth token hash from #extract_token.
+    # @return [OAuth2::AccessToken, nil] New access token object.
+    def create_and_assign_token(token_extract)
+      unless token_extract.nil?
+        @oauth_token = OAuth2::AccessToken.from_hash(@oauth, token_extract)
+      end
+    end
+
+    # Perform a GET request.
+    # @param path [String] The path at which to make ther request.
+    # @param params [Hash] A hash of request parameters.
+    def get(path, params = {})
+      request :get, path, params
+    end
+
+    # Perform a PUT request.
+    # @param path [String] The path at which to make ther request.
+    # @param params [Hash] A hash of request parameters.
+    def put(path, params = {})
+      request :put, path, params
+    end
+
+    # Perform a POST request.
+    # @param path [String] The path at which to make ther request.
+    # @param params [Hash] A hash of request parameters.
+    def post(path, params = {})
+      request :post, path, params
+    end
+
+    # Perform a DELETE request.
+    # @param path [String] The path at which to make ther request.
+    # @param params [Hash] A hash of request parameters.
+    def delete(path, params = {})
+      request :delete, path, params
+    end
+
+    private
+
+    def request(verb, path, params = {})
+      raise ArgumentError.new "Invalid http verb #{verb}" if ![:get, :post, :put, :delete].include?(verb)
+
+      params.merge!(utm_params)
+
+      if !Unsplash.configuration.utm_source
+        url = "https://community.unsplash.com/developersblog/unsplash-api-guidelines"
+        Unsplash.configuration.logger.warn "utm_source is required as part of API Terms: #{url}"
+      end
+
+      headers = {
+        "Accept-Version" => @api_version
+        # Anything else? User agent?
+      }
+
+      response = if @oauth_token
+        refresh_token!
+
+        param_key = verb == :post ? :body : :params
+        @oauth_token.public_send(verb,  @api_base_uri + path, param_key => params, headers: headers)
+      else
+        self.class.public_send verb, path, query: params, headers: public_auth_header
+      end
+
+      if response.headers["Warning"]
+        Unsplash.configuration.logger.warn response.headers["Warning"]
+      end
+
+      status_code = response.respond_to?(:status) ? response.status : response.code
+
+      if !(200..299).include?(status_code)
+        body = JSON.parse(response.body)
+        msg = body["error"] || body["errors"].join(" ")
+        raise Unsplash::Error.new msg
+      end
+
+      response
+    end
+
+    def public_auth_header
+      { "Authorization" => "Client-ID #{@application_access_key}" }
+    end
+
+    def utm_params
+      {
+        utm_source:   Unsplash.configuration.utm_source || "api_app",
+        utm_medium:   "referral",
+        utm_campaign: "api-credit"
+      }
+    end
+
+    def refresh_token!
+      return if !@oauth_token.expired?
+
+      @oauth_token = @oauth_token.refresh_token
+    end
+  end
+end

data/lib/unsplash/curated_batch.rb

@@ -0,0 +1,43 @@
+module Unsplash # :nodoc: 
+
+  # Unsplash Curated Batch operations.
+  class CuratedBatch < Client
+
+    class << self
+
+      # Get a specific curated batch.
+      # @param id [Integer] The ID of the batch.
+      # @return [Unsplash::CuratedBatch] The requested batch.
+      def find(id)
+        batch = Unsplash::CuratedBatch.new JSON.parse(connection.get("/curated_batches/#{id}").body)
+        batch.curator = Unsplash::User.new batch.curator
+        batch
+      end
+
+      # Get a list of all curated batches.
+      # @param page  [Integer] Which page of search results to return.
+      # @param per_page [Integer] The number of search results per page.
+      # @return [Array] A single page of the +Unsplash::CuratedBatch+ list.
+      def all(page = 1, per_page = 10)
+        params = {
+          page:     page,
+          per_page: per_page
+        }
+        list = JSON.parse(connection.get("/curated_batches/", params).body)
+        list.map do |cb|
+          batch = Unsplash::CuratedBatch.new cb
+          batch.curator = Unsplash::User.new batch.curator
+          batch
+        end
+      end
+    end
+
+    # Get a list of the photos contained in this batch.
+    # @return [Array] The list of +Unsplash::Photo+s in the batch.
+    def photos
+      list = JSON.parse(connection.get("/curated_batches/#{id}/photos").body)
+      list.map { |photo| Unsplash::Photo.new photo }
+    end
+
+  end
+end

data/lib/unsplash/errors.rb

@@ -0,0 +1,6 @@
+module Unsplash # :nodoc:
+  # Raised when there is an error communicating with Unsplash.
+  class Error < StandardError; end
+  # Raise for deprecation errors
+  class DeprecationError < Error; end
+end

data/lib/unsplash/photo.rb

@@ -0,0 +1,142 @@
+module Unsplash # :nodoc:
+
+  # Unsplash Photo operations.
+  class Photo < Client
+
+    # Like a photo for the current user.
+    # @return [Boolean] True if successful. Will raise on error.
+    def like!
+      connection.post("/photos/#{id}/like")
+      true
+    end
+
+    # Unlike a photo for the current user.
+    # @return [Boolean] True if successful. Will raise on error.
+    def unlike!
+      connection.delete("/photos/#{id}/like")
+      true
+    end
+
+    # Download a photo.
+    # @return [String] URL of image file for download.
+    def download!
+      connection.get(links.download_location)["url"]
+    end
+
+    class << self
+
+      # Get a photo. Can be cropped or resized using the optional parameters.
+      # @param id [String] The ID of the photo to retrieve.
+      # @param width [Integer] Width of customized version of the photo.
+      # @param height [Integer] Height of the customized version of the photo.
+      # @param crop_rect [String] A comma-separated list (x,y,width,height) of the rectangle to crop from the photo.
+      # @return [Unsplash::Photo] The Unsplash Photo.
+      def find(id, width: nil, height: nil, crop_rect: nil)
+        custom = {
+          w:    width,
+          h:    height,
+          rect: crop_rect
+        }.select { |k,v| v }
+        photo = Unsplash::Photo.new JSON.parse(connection.get("/photos/#{id}", custom).body)
+        photo.user = Unsplash::User.new photo.user
+        photo
+      end
+
+      # Get a random photo or set of photos. The photo selection pool can be narrowed using
+      # a combination of optional parameters. Can also optionally specify a custom image size.
+      # @param count [Integer] Number of photos required. Default=1, Max=30
+      # @param categories [Array] Limit selection to given category ID's.
+      # @param featured [Boolean] Limit selection to featured photos.
+      # @param user [String] Limit selection to given User's ID.
+      # @param query [String] Limit selection to given search query.
+      # @param width [Integer] Width of customized version of the photo.
+      # @param height [Integer] Height of the customized version of the photo.
+      # @param orientation [String] Filter by orientation of the photo. Valid values are landscape, portrait, and squarish.
+      # @return [Unsplash::Photo] An Unsplash Photo if count parameter is omitted
+      # @return [Array] An array of Unsplash Photos if the count parameter is specified. An array is returned even if count is 1
+      def random(count: nil, categories: nil, collections: nil, featured: nil, user: nil, query: nil, width: nil, height: nil, orientation: nil)
+        params = {
+          category: (categories && categories.join(",")),
+          collections: (collections && collections.join(",")),
+          featured: featured,
+          username: user,
+          query:    query,
+          w:        width,
+          h:        height,
+          orientation: orientation
+        }.select { |k,v| v }
+        if count
+          params[:count] = count
+          photos = parse_list connection.get("/photos/random/", params).body
+          photos.map { |photo|
+            photo.user = Unsplash::User.new photo[:user]
+            photo
+          }
+        else
+          photo = Unsplash::Photo.new JSON.parse(connection.get("/photos/random", params).body)
+          photo.user = Unsplash::User.new photo.user
+          photo
+        end
+      end
+
+      # Search for photos by keyword.
+      # @param query [String] Keywords to search for.
+      # @param page  [Integer] Which page of search results to return.
+      # @param per_page [Integer] The number of users search result per page. (default: 10, maximum: 30)
+      # @param orientation [String] Filter by orientation of the photo. Valid values are landscape, portrait, and squarish.
+      # @return [SearchResult] a list of +Unsplash::Photo+ objects.
+      def search(query, page = 1, per_page = 10, orientation = nil)
+        params = {
+          query:    query,
+          page:     page,
+          per_page: per_page,
+          orientation: orientation
+        }.select { |_k, v| v }
+        Unsplash::Search.search("/search/photos", self, params)
+      end
+
+      # Get a list of all photos.
+      # @param page  [Integer] Which page of search results to return.
+      # @param per_page [Integer] The number of search results per page. (default: 10, maximum: 30)
+      # @param order_by [String] How to sort the photos. (Valid values: latest, oldest, popular; default: latest)
+      # @return [Array] A single page of +Unsplash::Photo+ search results.
+      def all(page = 1, per_page = 10, order_by = "latest")
+        params = {
+          page:     page,
+          per_page: per_page,
+          order_by: order_by
+        }
+        parse_list connection.get("/photos/", params).body
+      end
+
+      # Get a single page from the list of the curated photos (front-page’s photos).
+      # @param page [Integer] Which page of search results to return.
+      # @param per_page [Integer] The number of search results per page. (default: 10, maximum: 30)
+      # @param order_by [String] How to sort the photos. (Valid values: latest, oldest, popular; default: latest)
+      # @return [Array] A single page of +Unsplash::Photo+ search results.
+      def curated(page = 1, per_page = 10, order_by = "latest")
+        params = {
+          page:     page,
+          per_page: per_page,
+          order_by: order_by
+        }
+        parse_list connection.get("/photos/curated", params).body
+      end
+
+      # Upload a photo on behalf of the current user.
+      # @param filepath [String] The local path of the image file to upload.
+      # @return [Unsplash::Photo] The uploaded photo.
+      # <b>DEPRECATED</b>
+      def create(filepath)
+        raise Unsplash::DeprecationError.new "API photo-upload endpoint has been deprecated and removed."
+      end
+
+      private
+
+      def parse_list(json)
+        JSON.parse(json).map { |photo| new photo }
+      end
+
+    end
+  end
+end

data/lib/unsplash/search.rb

@@ -0,0 +1,34 @@
+module Unsplash # :nodoc:
+
+  # Decorates Array of klass-type objects with total and total_pages attributes
+  class SearchResult < SimpleDelegator
+    attr_reader :total, :total_pages
+
+    def initialize(decorated, klass)
+      @total = decorated["total"]
+      @total_pages = decorated["total_pages"]
+
+      list = decorated["results"].map do |content|
+        klass.new content.to_hash
+      end
+
+      super(list)
+    end
+  end
+
+  # Unsplash Search operations
+  class Search < Client
+
+    class << self
+      # Helper class to facilitate search on multiple classes
+      # @param url [String] Url to be searched into
+      # @param klass [Class] Class to instantiate the contents with
+      # @param params [Hash] Params for the search
+      # @return [SearchResult] Decorated Array of klass-type objects
+      def search(url, klass, params)
+        list = JSON.parse(connection.get(url, params).body)
+        SearchResult.new(list, klass)
+      end
+    end
+  end
+end

data/lib/unsplash/stats.rb

@@ -0,0 +1,15 @@
+module Unsplash # :nodoc:
+
+  # Retrieve Unsplash stats
+  class Stats < Client
+
+    class << self
+      # Get a list of statistics regardling Unsplash as a whole.
+      # @return [Hash] The numbers.
+      def total
+        JSON.parse(connection.get("/stats/total").body)
+      end
+    end
+  end
+
+end

data/lib/unsplash/user.rb

@@ -0,0 +1,93 @@
+module Unsplash # :nodoc:
+
+  # Unsplash User operations.
+  class User < Client
+
+    class << self
+
+      # Get a user.
+      # @param username [String] the username of the user to retrieve.
+      # @return [Unsplash::User] the Unsplash User.
+      def find(username)
+        new JSON.parse(connection.get("/users/#{username}").body)
+      end
+
+      # Get the currently-logged in user.
+      # @return [Unsplash::User] the current user.
+      def current
+        new JSON.parse(connection.get("/me").body)
+      end
+
+      # Update the current user.
+      # @param params [Hash] the hash of attributes to update.
+      # @return [Unsplash::User] the updated user.
+      def update_current(params)
+        Unsplash::User.new JSON.parse(connection.put("/me", params).body)
+      end
+
+      # Get a single page of user results for a query.
+      # @param query [String] Keywords to search for.
+      # @param page  [Integer] Which page of search results to return.
+      # @param per_page [Integer] The number of users search result per page. (default: 10, maximum: 30)
+      # @return [Array] a list of +Unsplash::User+ objects.
+      def search(query, page = 1, per_page = 10)
+        params = {
+          query:    query,
+          page:     page,
+          per_page: per_page
+        }
+        Unsplash::Search.search("/search/users", self, params)
+      end
+
+    end
+
+    # Get a list of photos uploaded by the user.
+    # @param page  [Integer] Which page of results to return.
+    # @param per_page [Integer] The number of results per page.
+    # @return [Array] a list of +Unsplash::Photo+ objects.
+    def photos(page = 1, per_page = 10)
+      params = {
+        page:     page,
+        per_page: per_page
+      }
+
+      list = JSON.parse(connection.get("/users/#{username}/photos", params).body)
+      list.map do |photo|
+        Unsplash::Photo.new photo.to_hash
+      end
+    end
+
+    # Get a list of photos liked by the user.
+    # @param page  [Integer] Which page of results to return.
+    # @param per_page [Integer] The number of results per page. (default: 10, maximum: 30)
+    # @return [Array] a list of +Unsplash::Photo+ objects.
+    def likes(page = 1, per_page = 10)
+      params = {
+        page:     page,
+        per_page: per_page
+      }
+
+      list = JSON.parse(connection.get("/users/#{username}/likes", params).body)
+      list.map do |photo|
+        Unsplash::Photo.new photo.to_hash
+      end
+    end
+
+    # Get a list of collections created by the user.
+    # @param page  [Integer] Which page of results to return.
+    # @param per_page [Integer] The number of results per page. (default: 10, maximum: 30)
+    # @return [Array] a list of +Unsplash::Collection+ objects.
+    def collections(page = 1, per_page = 10)
+      params = {
+        page:     page,
+        per_page: per_page
+      }
+
+      list = JSON.parse(connection.get("/users/#{username}/collections", params).body)
+      list.map do |collection|
+        Unsplash::Collection.new collection.to_hash
+      end
+    end
+
+  end
+end