asana 0.0.6 → 0.1.1

data/lib/asana/authentication/oauth2/bearer_token_authentication.rb

@@ -0,0 +1,32 @@
+module Asana
+  module Authentication
+    module OAuth2
+      # Public: A mechanism to authenticate with an OAuth2 bearer token obtained
+      # somewhere, for instance through omniauth-asana.
+      #
+      # Note: This authentication mechanism doesn't support token refreshing. If
+      # you'd like refreshing and you have a refresh token as well as a bearer
+      # token, you can generate a proper access token with
+      # {AccessTokenAuthentication.from_refresh_token}.
+      class BearerTokenAuthentication
+        # Public: Initializes a new BearerTokenAuthentication with a plain
+        # bearer token.
+        #
+        # bearer_token - [String] a plain bearer token.
+        def initialize(bearer_token)
+          @token = bearer_token
+        end
+
+        # Public: Configures a Faraday connection injecting its token as an
+        # OAuth2 bearer token.
+        #
+        # connection - [Faraday::Connection] the Faraday connection instance.
+        #
+        # Returns nothing.
+        def configure(connection)
+          connection.request :oauth2, @token
+        end
+      end
+    end
+  end
+end

data/lib/asana/authentication/oauth2/client.rb

@@ -0,0 +1,50 @@
+require 'oauth2'
+
+module Asana
+  module Authentication
+    module OAuth2
+      # Public: Deals with the details of obtaining an OAuth2 authorization URL
+      # and obtaining access tokens from either authorization codes or refresh
+      # tokens.
+      class Client
+        # Public: Initializes a new client with client credentials associated
+        # with a registered Asana API application.
+        #
+        # client_id     - [String] a client id from the registered application
+        # client_secret - [String] a client secret from the registered
+        #                 application
+        # redirect_uri  - [String] a redirect uri from the registered
+        #                 application
+        def initialize(client_id: required('client_id'),
+                       client_secret: required('client_secret'),
+                       redirect_uri: required('redirect_uri'))
+          @client = ::OAuth2::Client.new(client_id, client_secret,
+                                         site: 'https://app.asana.com',
+                                         authorize_url: '/-/oauth_authorize',
+                                         token_url: '/-/oauth_token')
+          @redirect_uri = redirect_uri
+        end
+
+        # Public:
+        # Returns the [String] OAuth2 authorize URL.
+        def authorize_url
+          @client.auth_code.authorize_url(redirect_uri: @redirect_uri)
+        end
+
+        # Public: Retrieves a token from an authorization code.
+        #
+        # Returns the [::OAuth2::AccessToken] token.
+        def token_from_auth_code(auth_code)
+          @client.auth_code.get_token(auth_code, redirect_uri: @redirect_uri)
+        end
+
+        # Public: Retrieves a token from a refresh token.
+        #
+        # Returns the refreshed [::OAuth2::AccessToken] token.
+        def token_from_refresh_token(token)
+          ::OAuth2::AccessToken.new(@client, '', refresh_token: token).refresh!
+        end
+      end
+    end
+  end
+end

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,90 @@
+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