openc-asana 0.1.2

data/lib/asana/authentication/token_authentication.rb

@@ -0,0 +1,20 @@
+module Asana
+  module Authentication
+    # Public: Represents an API token authentication mechanism.
+    class TokenAuthentication
+      def initialize(token)
+        @token = token
+      end
+
+      # Public: Configures a Faraday connection injecting its token as
+      # basic auth.
+      #
+      # builder - [Faraday::Connection] the Faraday connection instance.
+      #
+      # Returns nothing.
+      def configure(connection)
+        connection.basic_auth(@token, '')
+      end
+    end
+  end
+end

data/lib/asana/client.rb

@@ -0,0 +1,124 @@
+require_relative 'authentication'
+require_relative 'client/configuration'
+require_relative 'resources'
+
+module Asana
+  # Public: A client to interact with the Asana API. It exposes all the
+  # available resources of the Asana API in idiomatic Ruby.
+  #
+  # Examples
+  #
+  #   # Authentication with an API token
+  #   Asana::Client.new do |client|
+  #     client.authentication :api_token, '...'
+  #   end
+  #
+  #   # OAuth2 with a plain bearer token (doesn't support auto-refresh)
+  #   Asana::Client.new do |client|
+  #     client.authentication :oauth2, bearer_token: '...'
+  #   end
+  #
+  #   # OAuth2 with a plain refresh token and client credentials
+  #   Asana::Client.new do |client|
+  #     client.authentication :oauth2,
+  #                           refresh_token: '...',
+  #                           client_id: '...',
+  #                           client_secret: '...',
+  #                           redirect_uri: '...'
+  #   end
+  #
+  #   # OAuth2 with an ::OAuth2::AccessToken object
+  #   Asana::Client.new do |client|
+  #     client.authentication :oauth2, my_oauth2_access_token_object
+  #   end
+  #
+  #   # Use a custom Faraday network adapter
+  #   Asana::Client.new do |client|
+  #     client.authentication ...
+  #     client.adapter :typhoeus
+  #   end
+  #
+  #   # Use a custom user agent string
+  #   Asana::Client.new do |client|
+  #     client.authentication ...
+  #     client.user_agent '...'
+  #   end
+  #
+  #   # Pass in custom configuration to the Faraday connection
+  #   Asana::Client.new do |client|
+  #     client.authentication ...
+  #     client.configure_faraday { |conn| conn.use MyMiddleware }
+  #   end
+  #
+  class Client
+    # Internal: Proxies Resource classes to implement a fluent API on the Client
+    # instances.
+    class ResourceProxy
+      def initialize(client: required('client'), resource: required('resource'))
+        @client   = client
+        @resource = resource
+      end
+
+      def method_missing(m, *args, &block)
+        @resource.public_send(m, *([@client] + args), &block)
+      end
+
+      def respond_to_missing?(m, *)
+        @resource.respond_to?(m)
+      end
+    end
+
+    # Public: Initializes a new client.
+    #
+    # Yields a {Asana::Client::Configuration} object as a configuration
+    # DSL. See {Asana::Client} for usage examples.
+    def initialize
+      config = Configuration.new.tap { |c| yield c }.to_h
+      @http_client =
+        HttpClient.new(authentication: config.fetch(:authentication),
+                       adapter:        config[:faraday_adapter],
+                       user_agent:     config[:user_agent],
+                       debug_mode:     config[:debug_mode],
+                       &config[:faraday_config])
+    end
+
+    # Public: Performs a GET request against an arbitrary Asana URL. Allows for
+    # the user to interact with the API in ways that haven't been
+    # reflected/foreseen in this library.
+    def get(url, *args)
+      @http_client.get(url, *args)
+    end
+
+    # Public: Performs a POST request against an arbitrary Asana URL. Allows for
+    # the user to interact with the API in ways that haven't been
+    # reflected/foreseen in this library.
+    def post(url, *args)
+      @http_client.post(url, *args)
+    end
+
+    # Public: Performs a PUT request against an arbitrary Asana URL. Allows for
+    # the user to interact with the API in ways that haven't been
+    # reflected/foreseen in this library.
+    def put(url, *args)
+      @http_client.put(url, *args)
+    end
+
+    # Public: Performs a DELETE request against an arbitrary Asana URL. Allows
+    # for the user to interact with the API in ways that haven't been
+    # reflected/foreseen in this library.
+    def delete(url, *args)
+      @http_client.delete(url, *args)
+    end
+
+    # Public: Exposes queries for all top-evel endpoints.
+    #
+    # E.g. #users will query /users and return a
+    # Asana::Resources::Collection<User>.
+    Resources::Registry.resources.each do |resource_class|
+      define_method(resource_class.plural_name) do
+        ResourceProxy.new(client: @http_client,
+                          resource: resource_class)
+      end
+    end
+  end
+end

data/lib/asana/client/configuration.rb

@@ -0,0 +1,165 @@
+module Asana
+  class Client
+    # Internal: Represents a configuration DSL for an Asana::Client.
+    #
+    # Examples
+    #
+    #   config = Configuration.new
+    #   config.authentication :api_token, 'my_api_token'
+    #   config.adapter :typhoeus
+    #   config.configure_faraday { |conn| conn.use MyMiddleware }
+    #   config.to_h
+    #   # => { authentication: #<Authentication::TokenAuthentication>,
+    #          faraday_adapter: :typhoeus,
+    #          faraday_configuration: #<Proc> }
+    #
+    class Configuration
+      # Public: Initializes an empty configuration object.
+      def initialize
+        @configuration = {}
+      end
+
+      # Public: Sets an authentication strategy.
+      #
+      # type  - [:oauth2, :api_token] the kind of authentication strategy to use
+      # value - [::OAuth2::AccessToken, String, Hash] the configuration for the
+      #         chosen authentication strategy.
+      #
+      # Returns nothing.
+      #
+      # Raises ArgumentError if the arguments are invalid.
+      def authentication(type, value)
+        auth = case type
+               when :oauth2    then oauth2(value)
+               when :api_token then api_token(value)
+               else error "unsupported authentication type #{type}"
+               end
+        @configuration[:authentication] = auth
+      end
+
+      # Public: Sets a custom network adapter for Faraday.
+      #
+      # adapter - [Symbol, Proc] the adapter.
+      #
+      # Returns nothing.
+      def faraday_adapter(adapter)
+        @configuration[:faraday_adapter] = adapter
+      end
+
+      # Public: Sets a custom configuration block for the Faraday connection.
+      #
+      # config - [Proc] the configuration block.
+      #
+      # Returns nothing.
+      def configure_faraday(&config)
+        @configuration[:faraday_configuration] = config
+      end
+
+      # Public: Configures the client in debug mode, which will print verbose
+      # information on STDERR.
+      #
+      # Returns nothing.
+      def debug_mode
+        @configuration[:debug_mode] = true
+      end
+
+      # Public:
+      # Returns the configuration [Hash].
+      def to_h
+        @configuration
+      end
+
+      private
+
+      # Internal: Configures an OAuth2 authentication strategy from either an
+      # OAuth2 access token object, or a plain refresh token, or a plain bearer
+      # token.
+      #
+      # value - [::OAuth::AccessToken, String] the value to configure the
+      #         strategy from.
+      #
+      # Returns [Asana::Authentication::OAuth2::AccessTokenAuthentication,
+      #          Asana::Authentication::OAuth2::BearerTokenAuthentication]
+      #         the OAuth2 authentication strategy.
+      #
+      # Raises ArgumentError if the OAuth2 configuration arguments are invalid.
+      #
+      # rubocop:disable Metrics/MethodLength
+      def oauth2(value)
+        case value
+        when ::OAuth2::AccessToken
+          from_access_token(value)
+        when -> v { v.is_a?(Hash) && v[:refresh_token] }
+          from_refresh_token(value)
+        when -> v { v.is_a?(Hash) && v[:bearer_token] }
+          from_bearer_token(value[:bearer_token])
+        else
+          error 'Invalid OAuth2 configuration: pass in either an ' \
+            '::OAuth2::AccessToken object of your own or a hash ' \
+            'containing :refresh_token or :bearer_token.'
+        end
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # Internal: Configures a TokenAuthentication strategy.
+      #
+      # token - [String] the API token
+      #
+      # Returns a [Authentication::TokenAuthentication] strategy.
+      def api_token(token)
+        Authentication::TokenAuthentication.new(token)
+      end
+
+      # Internal: Configures an OAuth2 AccessTokenAuthentication strategy.
+      #
+      # access_token - [::OAuth2::AccessToken] the OAuth2 access token object
+      #
+      # Returns a [Authentication::OAuth2::AccessTokenAuthentication] strategy.
+      def from_access_token(access_token)
+        Authentication::OAuth2::AccessTokenAuthentication
+          .new(access_token)
+      end
+
+      # Internal: Configures an OAuth2 AccessTokenAuthentication strategy.
+      #
+      # hash - The configuration hash:
+      #        :refresh_token - [String] the OAuth2 refresh token
+      #        :client_id     - [String] the OAuth2 client id
+      #        :client_secret - [String] the OAuth2 client secret
+      #        :redirect_uri  - [String] the OAuth2 redirect URI
+      #
+      # Returns a [Authentication::OAuth2::AccessTokenAuthentication] strategy.
+      def from_refresh_token(hash)
+        refresh_token, client_id, client_secret, redirect_uri =
+          requiring(hash, :refresh_token, :client_id,
+                    :client_secret, :redirect_uri)
+
+        Authentication::OAuth2::AccessTokenAuthentication
+          .from_refresh_token(refresh_token,
+                              client_id: client_id,
+                              client_secret: client_secret,
+                              redirect_uri: redirect_uri)
+      end
+
+      # Internal: Configures an OAuth2 BearerTokenAuthentication strategy.
+      #
+      # bearer_token - [String] the plain OAuth2 bearer token
+      #
+      # Returns a [Authentication::OAuth2::BearerTokenAuthentication] strategy.
+      def from_bearer_token(bearer_token)
+        Authentication::OAuth2::BearerTokenAuthentication
+          .new(bearer_token)
+      end
+
+      def requiring(hash, *keys)
+        missing_keys = keys.select { |k| !hash.key?(k) }
+        missing_keys.any? && error("Missing keys: #{missing_keys.join(', ')}")
+        keys.map { |k| hash[k] }
+      end
+
+      def error(msg)
+        fail ArgumentError, msg
+      end
+    end
+  end
+end

data/lib/asana/errors.rb

@@ -0,0 +1,92 @@
+module Asana
+  # Public: Defines the different errors that the Asana API may throw, which the
+  # client code may want to catch.
+  module Errors
+    # Public: A generic, catch-all API error. It contains the whole response
+    # object for debugging purposes.
+    #
+    # Note: This exception should never be raised when there exists a more
+    # specific subclass.
+    APIError = Class.new(StandardError) do
+      attr_accessor :response
+
+      def to_s
+        'An unknown API error ocurred.'
+      end
+    end
+
+    # Public: A 401 error. Raised when the credentials used are invalid and the
+    # user could not be authenticated.
+    NotAuthorized = Class.new(APIError) do
+      def to_s
+        'A valid API key was not provided with the request, so the API could '\
+        'not associate a user with the request.'
+      end
+    end
+
+    # Public: A 403 error. Raised when the user doesn't have permission to
+    # access the requested resource or to perform the requested action on it.
+    Forbidden = Class.new(APIError) do
+      def to_s
+        'The API key and request syntax was valid but the server is refusing '\
+        'to complete the request. This can happen if you try to read or write '\
+        'to objects or properties that the user does not have access to.'
+      end
+    end
+
+    # Public: A 404 error. Raised when the requested resource doesn't exist.
+    NotFound = Class.new(APIError) do
+      def to_s
+        'Either the request method and path supplied do not specify a known '\
+        'action in the API, or the object specified by the request does not '\
+        'exist.'
+      end
+    end
+
+    # Public: A 500 error. Raised when there is a problem in the Asana API
+    # server. It contains a unique phrase that can be used to identify the
+    # problem when contacting developer support.
+    ServerError = Class.new(APIError) do
+      attr_accessor :phrase
+
+      def initialize(phrase)
+        @phrase = phrase
+      end
+
+      def to_s
+        "There has been an error on Asana's end. Use this unique phrase to "\
+        'identify the problem when contacting developer support: ' +
+        %("#{@phrase}")
+      end
+    end
+
+    # Public: A 400 error. Raised when the request was malformed or missing some
+    # parameters. It contains a list of errors indicating the specific problems.
+    InvalidRequest = Class.new(APIError) do
+      attr_accessor :errors
+
+      def initialize(errors)
+        @errors = errors
+      end
+
+      def to_s
+        errors.join(', ')
+      end
+    end
+
+    # Public: A 429 error. Raised when the Asana API enforces rate-limiting on
+    # the client to avoid overload. It contains the number of seconds to wait
+    # before retrying the operation.
+    RateLimitEnforced = Class.new(APIError) do
+      attr_accessor :retry_after_seconds
+
+      def initialize(retry_after_seconds)
+        @retry_after_seconds = retry_after_seconds
+      end
+
+      def to_s
+        "Retry your request after #{@retry_after_seconds} seconds."
+      end
+    end
+  end
+end

data/lib/asana/http_client.rb

@@ -0,0 +1,155 @@
+require 'faraday'
+require 'faraday_middleware'
+require 'faraday_middleware/multi_json'
+
+require_relative 'http_client/error_handling'
+require_relative 'http_client/environment_info'
+require_relative 'http_client/response'
+
+module Asana
+  # Internal: Wrapper over Faraday that abstracts authentication, request
+  # parsing and common options.
+  class HttpClient
+    # Internal: The API base URI.
+    BASE_URI = 'https://app.asana.com/api/1.0'
+
+    # Public: Initializes an HttpClient to make requests to the Asana API.
+    #
+    # authentication - [Asana::Authentication] An authentication strategy.
+    # adapter        - [Symbol, Proc] A Faraday adapter, eiter a Symbol for
+    #                  registered adapters or a Proc taking a builder for a
+    #                  custom one. Defaults to Faraday.default_adapter.
+    # user_agent     - [String] The user agent. Defaults to "ruby-asana vX.Y.Z".
+    # config         - [Proc] An optional block that yields the Faraday builder
+    #                  object for customization.
+    def initialize(authentication: required('authentication'),
+                   adapter: nil,
+                   user_agent: nil,
+                   debug_mode: false,
+                   &config)
+      @authentication   = authentication
+      @adapter          = adapter || Faraday.default_adapter
+      @environment_info = EnvironmentInfo.new(user_agent)
+      @debug_mode       = debug_mode
+      @config           = config
+    end
+
+    # Public: Performs a GET request against the API.
+    #
+    # resource_uri - [String] the resource URI relative to the base Asana API
+    #                URL, e.g "/users/me".
+    # params       - [Hash] the request parameters
+    # options      - [Hash] the request I/O options
+    #
+    # Returns an [Asana::HttpClient::Response] if everything went well.
+    # Raises [Asana::Errors::APIError] if anything went wrong.
+    def get(resource_uri, params: {}, options: {})
+      opts = options.reduce({}) do |acc, (k, v)|
+        acc.tap do |hash|
+          hash[:"opt_#{k}"] = v.is_a?(Array) ? v.join(',') : v
+        end
+      end
+      perform_request(:get, resource_uri, params.merge(opts))
+    end
+
+    # Public: Performs a PUT request against the API.
+    #
+    # resource_uri - [String] the resource URI relative to the base Asana API
+    #                URL, e.g "/users/me".
+    # body         - [Hash] the body to PUT.
+    # options      - [Hash] the request I/O options
+    #
+    # Returns an [Asana::HttpClient::Response] if everything went well.
+    # Raises [Asana::Errors::APIError] if anything went wrong.
+    def put(resource_uri, body: {}, options: {})
+      params = { data: body }.merge(options.empty? ? {} : { options: options })
+      perform_request(:put, resource_uri, params)
+    end
+
+    # Public: Performs a POST request against the API.
+    #
+    # resource_uri - [String] the resource URI relative to the base Asana API
+    #                URL, e.g "/tags".
+    # body         - [Hash] the body to POST.
+    # upload       - [Faraday::UploadIO] an upload object to post as multipart.
+    #                Defaults to nil.
+    # options      - [Hash] the request I/O options
+    #
+    # Returns an [Asana::HttpClient::Response] if everything went well.
+    # Raises [Asana::Errors::APIError] if anything went wrong.
+    def post(resource_uri, body: {}, upload: nil, options: {})
+      params = { data: body }.merge(options.empty? ? {} : { options: options })
+      if upload
+        perform_request(:post, resource_uri, params.merge(file: upload)) do |c|
+          c.request :multipart
+        end
+      else
+        perform_request(:post, resource_uri, params)
+      end
+    end
+
+    # Public: Performs a DELETE request against the API.
+    #
+    # resource_uri - [String] the resource URI relative to the base Asana API
+    #                URL, e.g "/tags".
+    #
+    # Returns an [Asana::HttpClient::Response] if everything went well.
+    # Raises [Asana::Errors::APIError] if anything went wrong.
+    def delete(resource_uri)
+      perform_request(:delete, resource_uri)
+    end
+
+    private
+
+    def connection(&request_config)
+      Faraday.new do |builder|
+        @authentication.configure(builder)
+        @environment_info.configure(builder)
+        request_config.call(builder) if request_config
+        configure_format(builder)
+        add_middleware(builder)
+        @config.call(builder) if @config
+        use_adapter(builder, @adapter)
+      end
+    end
+
+    def perform_request(method, resource_uri, body = {}, &request_config)
+      handling_errors do
+        url = BASE_URI + resource_uri
+        log_request(method, url, body) if @debug_mode
+        Response.new(connection(&request_config).public_send(method, url, body))
+      end
+    end
+
+    def configure_format(builder)
+      builder.request :multi_json
+      builder.response :multi_json
+    end
+
+    def add_middleware(builder)
+      builder.use Faraday::Response::RaiseError
+      builder.use FaradayMiddleware::FollowRedirects
+    end
+
+    def use_adapter(builder, adapter)
+      case adapter
+      when Symbol
+        builder.adapter(adapter)
+      when Proc
+        adapter.call(builder)
+      end
+    end
+
+    def handling_errors(&request)
+      ErrorHandling.handle(&request)
+    end
+
+    def log_request(method, url, body)
+      STDERR.puts format('[%s] %s %s (%s)',
+                         self.class,
+                         method.to_s.upcase,
+                         url,
+                         body.inspect)
+    end
+  end
+end