asana 0.0.6 → 0.1.1

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

data/lib/asana/http_client/environment_info.rb

@@ -0,0 +1,53 @@
+require_relative '../version'
+require 'openssl'
+
+module Asana
+  class HttpClient
+    # Internal: Adds environment information to a Faraday request.
+    class EnvironmentInfo
+      # Internal: The default user agent to use in all requests to the API.
+      USER_AGENT = "ruby-asana v#{Asana::VERSION}"
+
+      def initialize(user_agent = nil)
+        @user_agent = user_agent || USER_AGENT
+        @openssl_version = OpenSSL::OPENSSL_VERSION
+        @client_version = Asana::VERSION
+        @os = os
+      end
+
+      # Public: Augments a Faraday connection with information about the
+      # environment.
+      def configure(builder)
+        builder.headers[:user_agent] = @user_agent
+        builder.headers[:"X-Asana-Client-Lib"] = header
+      end
+
+      private
+
+      def header
+        { os: @os,
+          language: 'ruby',
+          language_version: RUBY_VERSION,
+          version: @client_version,
+          openssl_version: @openssl_version }
+          .map { |k, v| "#{k}=#{v}" }.join('&')
+      end
+
+      # rubocop:disable Metrics/MethodLength
+      def os
+        if RUBY_PLATFORM =~ /win32/ || RUBY_PLATFORM =~ /mingw/
+          'windows'
+        elsif RUBY_PLATFORM =~ /linux/
+          'linux'
+        elsif RUBY_PLATFORM =~ /darwin/
+          'darwin'
+        elsif RUBY_PLATFORM =~ /freebsd/
+          'freebsd'
+        else
+          'unknown'
+        end
+      end
+      # rubocop:enable Metrics/MethodLength
+    end
+  end
+end

data/lib/asana/http_client/error_handling.rb

@@ -0,0 +1,103 @@
+require 'multi_json'
+
+require_relative '../errors'
+
+module Asana
+  class HttpClient
+    # Internal: Handles errors from the API and re-raises them as proper
+    # exceptions.
+    module ErrorHandling
+      include Errors
+
+      module_function
+
+      # Public: Perform a request handling any API errors correspondingly.
+      #
+      # request - [Proc] a block that will execute the request.
+      #
+      # Returns a [Faraday::Response] object.
+      #
+      # Raises [Asana::Errors::InvalidRequest] for invalid requests.
+      # Raises [Asana::Errors::NotAuthorized] for unauthorized requests.
+      # Raises [Asana::Errors::Forbidden] for forbidden requests.
+      # Raises [Asana::Errors::NotFound] when a resource can't be found.
+      # Raises [Asana::Errors::RateLimitEnforced] when the API is throttling.
+      # Raises [Asana::Errors::ServerError] when there's a server problem.
+      # Raises [Asana::Errors::APIError] when the API returns an unknown error.
+      #
+      # rubocop:disable all
+      def handle(&request)
+        request.call
+      rescue Faraday::ClientError => e
+        raise e unless e.response
+        case e.response[:status]
+        when 400 then raise invalid_request(e.response)
+        when 401 then raise not_authorized(e.response)
+        when 403 then raise forbidden(e.response)
+        when 404 then raise not_found(e.response)
+        when 412 then recover_response(e.response)
+        when 429 then raise rate_limit_enforced(e.response)
+        when 500 then raise server_error(e.response)
+        else raise api_error(e.response)
+        end
+      end
+      # rubocop:enable all
+
+      # Internal: Returns an InvalidRequest exception including a list of
+      # errors.
+      def invalid_request(response)
+        errors = body(response).fetch('errors', []).map { |e| e['message'] }
+        InvalidRequest.new(errors).tap do |exception|
+          exception.response = response
+        end
+      end
+
+      # Internal: Returns a NotAuthorized exception.
+      def not_authorized(response)
+        NotAuthorized.new.tap { |exception| exception.response = response }
+      end
+
+      # Internal: Returns a Forbidden exception.
+      def forbidden(response)
+        Forbidden.new.tap { |exception| exception.response = response }
+      end
+
+      # Internal: Returns a NotFound exception.
+      def not_found(response)
+        NotFound.new.tap { |exception| exception.response = response }
+      end
+
+      # Internal: Returns a RateLimitEnforced exception with a retry after
+      # field.
+      def rate_limit_enforced(response)
+        retry_after_seconds = response[:headers]['Retry-After']
+        RateLimitEnforced.new(retry_after_seconds).tap do |exception|
+          exception.response = response
+        end
+      end
+
+      # Internal: Returns a ServerError exception with a unique phrase.
+      def server_error(response)
+        phrase = body(response).fetch('errors', []).first['phrase']
+        ServerError.new(phrase).tap do |exception|
+          exception.response = response
+        end
+      end
+
+      # Internal: Returns an APIError exception.
+      def api_error(response)
+        APIError.new.tap { |exception| exception.response = response }
+      end
+
+      # Internal: Parser a response body from JSON.
+      def body(response)
+        MultiJson.load(response[:body])
+      end
+
+      def recover_response(response)
+        r = response.dup.tap { |res| res[:body] = body(response) }
+        Response.new(OpenStruct.new(env: OpenStruct.new(r)))
+      end
+    end
+  end
+end

data/lib/asana/http_client/response.rb

@@ -0,0 +1,32 @@
+module Asana
+  class HttpClient
+    # Internal: Represents a response from the Asana API.
+    class Response
+      # Public:
+      # Returns a [Faraday::Env] object for debugging.
+      attr_reader :faraday_env
+      # Public:
+      # Returns the [Integer] status code of the response.
+      attr_reader :status
+      # Public:
+      # Returns the [Hash] representing the parsed JSON body.
+      attr_reader :body
+
+      # Public: Wraps a Faraday response.
+      #
+      # faraday_response - [Faraday::Response] the Faraday response to wrap.
+      def initialize(faraday_response)
+        @faraday_env = faraday_response.env
+        @status      = faraday_env.status
+        @body        = faraday_env.body
+      end
+
+      # Public:
+      # Returns a [String] representation of the response.
+      def to_s
+        "#<Asana::HttpClient::Response status=#{@status} body=#{@body}>"
+      end
+      alias_method :inspect, :to_s
+    end
+  end
+end

data/lib/asana/resources.rb

@@ -0,0 +1,11 @@
+require_relative 'resources/resource'
+require_relative 'resources/collection'
+
+Dir[File.join(File.dirname(__FILE__), 'resources', '*.rb')]
+  .each { |resource| require resource }
+
+module Asana
+  # Public: Contains all the resources that the Asana API can return.
+  module Resources
+  end
+end

data/lib/asana/resources/attachment.rb

@@ -0,0 +1,44 @@
+### WARNING: This file is auto-generated by the asana-api-meta repo. Do not
+### edit it manually.
+
+module Asana
+  module Resources
+    # An _attachment_ object represents any file attached to a task in Asana,
+    # whether it's an uploaded file or one associated via a third-party service
+    # such as Dropbox or Google Drive.
+    class Attachment < Resource
+
+
+      attr_reader :id
+
+      class << self
+        # Returns the plural name of the resource.
+        def plural_name
+          'attachments'
+        end
+
+        # Returns the full record for a single attachment.
+        #
+        # id - [Id] Globally unique identifier for the attachment.
+        #
+        # options - [Hash] the request I/O options.
+        def find_by_id(client, id, options: {})
+
+          self.new(parse(client.get("/attachments/#{id}", options: options)).first, client: client)
+        end
+
+        # Returns the compact records for all attachments on the task.
+        #
+        # task - [Id] Globally unique identifier for the task.
+        #
+        # per_page - [Integer] the number of records to fetch per page.
+        # options - [Hash] the request I/O options.
+        def find_by_task(client, task: required("task"), per_page: 20, options: {})
+          params = { limit: per_page }.reject { |_,v| v.nil? || Array(v).empty? }
+          Collection.new(parse(client.get("/tasks/#{task}/attachments", params: params, options: options)), type: self, client: client)
+        end
+      end
+
+    end
+  end
+end

data/lib/asana/resources/attachment_uploading.rb

@@ -0,0 +1,33 @@
+module Asana
+  module Resources
+    # Internal: Mixin to add the ability to upload an attachment to a specific
+    # Asana resource (a Task, really).
+    module AttachmentUploading
+      # Uploads a new attachment to the resource.
+      #
+      # filename - [String] the absolute path of the file to upload.
+      # mime     - [String] the MIME type of the file
+      # options  - [Hash] the request I/O options
+      # data     - [Hash] extra attributes to post
+      #
+      # rubocop:disable Metrics/AbcSize
+      # rubocop:disable Metrics/MethodLength
+      def attach(filename: required('filename'),
+                 mime: required('mime'),
+                 options: {}, **data)
+        path = File.expand_path(filename)
+        unless File.exist?(path)
+          fail ArgumentError, "file #{filename} doesn't exist"
+        end
+        upload = Faraday::UploadIO.new(path, mime)
+        response = client.post("/#{self.class.plural_name}/#{id}/attachments",
+                               body: data,
+                               upload: upload,
+                               options: options)
+        Attachment.new(parse(response).first, client: client)
+      end
+      # rubocop:enable Metrics/MethodLength
+      # rubocop:enable Metrics/AbcSize
+    end
+  end
+end

data/lib/asana/resources/collection.rb

@@ -0,0 +1,68 @@
+require_relative 'response_helper'
+
+module Asana
+  module Resources
+    # Public: Represents a paginated collection of Asana resources.
+    class Collection
+      include Enumerable
+      include ResponseHelper
+
+      attr_reader :elements
+
+      # Public: Initializes a collection representing a page of resources of a
+      # given type.
+      #
+      # (elements, extra) - [Array] an (String, Hash) tuple coming from the
+      #                     response parser.
+      # type              - [Class] the type of resource that the collection
+      #                     contains. Defaults to the generic Resource.
+      # client            - [Asana::Client] the client to perform requests.
+      def initialize((elements, extra),
+                     type: Resource,
+                     client: required('client'))
+        @elements       = elements.map { |elem| type.new(elem, client: client) }
+        @type           = type
+        @next_page_data = extra['next_page']
+        @client         = client
+      end
+
+      # Public: Iterates over the elements of the collection.
+      def each(&block)
+        if block
+          @elements.each(&block)
+          (next_page || []).each(&block)
+        else
+          to_enum
+        end
+      end
+
+      # Public: Returns the size of the collection.
+      def size
+        to_a.size
+      end
+      alias_method :length, :size
+
+      # Public: Returns a String representation of the collection.
+      def to_s
+        "#<Asana::Collection<#{@type}> " \
+          "[#{@elements.map(&:inspect).join(', ')}" +
+          (@next_page_data ? ', ...' : '') + ']>'
+      end
+
+      alias_method :inspect, :to_s
+
+      # Public: Returns a new Asana::Resources::Collection with the next page
+      # or nil if there are no more pages. Caches the result.
+      def next_page
+        if defined?(@next_page)
+          @next_page
+        else
+          @next_page = if @next_page_data
+                         response = parse(@client.get(@next_page_data['path']))
+                         self.class.new(response, type: @type, client: @client)
+                       end
+        end
+      end
+    end
+  end
+end