openc-asana 0.1.2

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/resource_includes/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/resource_includes/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

data/lib/asana/resource_includes/event.rb

@@ -0,0 +1,51 @@
+require_relative 'events'
+
+module Asana
+  module Resources
+    # An _event_ is an object representing a change to a resource that was
+    # observed by an event subscription.
+    #
+    # In general, requesting events on a resource is faster and subject to
+    # higher rate limits than requesting the resource itself. Additionally,
+    # change events bubble up - listening to events on a project would include
+    # when stories are added to tasks in the project, even on subtasks.
+    #
+    # Establish an initial sync token by making a request with no sync token.
+    # The response will be a `412` error - the same as if the sync token had
+    # expired.
+    #
+    # Subsequent requests should always provide the sync token from the
+    # immediately preceding call.
+    #
+    # Sync tokens may not be valid if you attempt to go 'backward' in the
+    # history by requesting previous tokens, though re-requesting the current
+    # sync token is generally safe, and will always return the same results.
+    #
+    # When you receive a `412 Precondition Failed` error, it means that the sync
+    # token is either invalid or expired. If you are attempting to keep a set of
+    # data in sync, this signals you may need to re-crawl the data.
+    #
+    # Sync tokens always expire after 24 hours, but may expire sooner, depending
+    # on load on the service.
+    class Event < Resource
+      attr_reader :type
+
+      class << self
+        # Returns the plural name of the resource.
+        def plural_name
+          'events'
+        end
+
+        # Public: Returns an infinite collection of events on a particular
+        # resource.
+        #
+        # client - [Asana::Client] the client to perform the requests.
+        # id     - [String] the id of the resource to get events from.
+        # wait   - [Integer] the number of seconds to wait between each poll.
+        def for(client, id, wait: 1)
+          Events.new(resource: id, client: client, wait: wait)
+        end
+      end
+    end
+  end
+end

data/lib/asana/resource_includes/event_subscription.rb

@@ -0,0 +1,14 @@
+require_relative 'events'
+
+module Asana
+  module Resources
+    # Public: Mixin to enable a resource with the ability to fetch events about
+    # itself.
+    module EventSubscription
+      # Public: Returns an infinite collection of events on the resource.
+      def events(wait: 1, options: {})
+        Events.new(resource: id, client: client, wait: wait, options: options)
+      end
+    end
+  end
+end

data/lib/asana/resource_includes/events.rb

@@ -0,0 +1,103 @@
+require_relative 'event'
+
+module Asana
+  module Resources
+    # Public: An infinite collection of events.
+    #
+    # Since they are infinite, if you want to filter or do other collection
+    # operations without blocking indefinitely you should call #lazy on them to
+    # turn them into a lazy collection.
+    #
+    # Examples:
+    #
+    #   # Subscribes to an event stream and blocks indefinitely, printing
+    #   # information of every event as it comes in.
+    #   events = Events.new(resource: 'someresourceID', client: client)
+    #   events.each do |event|
+    #     puts [event.type, event.action]
+    #   end
+    #
+    #   # Lazily filters events as they come in and prints them.
+    #   events = Events.new(resource: 'someresourceID', client: client)
+    #   events.lazy.select { |e| e.type == 'task' }.each do |event|
+    #     puts [event.type, event.action]
+    #   end
+    #
+    class Events
+      include Enumerable
+
+      # Public: Initializes a new Events instance, subscribed to a resource ID.
+      #
+      # resource - [String] a resource ID. Can be a task id or a workspace id.
+      # client   - [Asana::Client] a client to perform the requests.
+      # wait     - [Integer] the number of seconds to wait between each poll.
+      # options  - [Hash] the request I/O options
+      def initialize(resource: required('resource'),
+                     client: required('client'),
+                     wait: 1, options: {})
+        @resource  = resource
+        @client    = client
+        @events    = []
+        @wait      = wait
+        @options   = options
+        @sync      = nil
+        @last_poll = nil
+      end
+
+      # Public: Iterates indefinitely over all events happening to a particular
+      # resource from the @sync timestamp or from now if it is nil.
+      def each(&block)
+        if block
+          loop do
+            poll if @events.empty?
+            event = @events.shift
+            yield event if event
+          end
+        else
+          to_enum
+        end
+      end
+
+      private
+
+      # Internal: Polls and fetches all events that have occurred since the sync
+      # token was created. Updates the sync token as it comes back from the
+      # response.
+      #
+      # If we polled less than @wait seconds ago, we don't do anything.
+      #
+      # Notes:
+      #
+      # On the first request, the sync token is not passed (because it is
+      # nil). The response will be the same as for an expired sync token, and
+      # will include a new valid sync token.
+      #
+      # If the sync token is too old (which may happen from time to time)
+      # the API will return a `412 Precondition Failed` error, and include
+      # a fresh `sync` token in the response.
+      def poll
+        rate_limiting do
+          body     = @client.get('/events',
+                                 params: params,
+                                 options: @options).body
+          @sync    = body['sync']
+          @events += body.fetch('data', []).map do |event_data|
+            Event.new(event_data, client: @client)
+          end
+        end
+      end
+
+      # Internal: Returns the formatted params for the poll request.
+      def params
+        { resource: @resource, sync: @sync }.reject { |_, v| v.nil? }
+      end
+
+      # Internal: Executes a block if at least @wait seconds have passed since
+      # @last_poll.
+      def rate_limiting(&block)
+        return if @last_poll && Time.now - @last_poll <= @wait
+        block.call.tap { @last_poll = Time.now }
+      end
+    end
+  end
+end