asana 0.0.6 → 0.1.1

data/lib/asana/resources/event.rb

@@ -0,0 +1,49 @@
+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/resources/event_subscription.rb

@@ -0,0 +1,12 @@
+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/resources/events.rb

@@ -0,0 +1,101 @@
+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

data/lib/asana/resources/project.rb

@@ -1,28 +1,154 @@
+### WARNING: This file is auto-generated by the asana-api-meta repo. Do not
+### edit it manually.
+
 module Asana
-  class Project < Asana::Resource
+  module Resources
+    # A _project_ represents a prioritized list of tasks in Asana. It exists in a
+    # single workspace or organization and is accessible to a subset of users in
+    # that workspace or organization, depending on its permissions.
+    #
+    # Projects in organizations are shared with a single team. You cannot currently
+    # change the team of a project via the API. Non-organization workspaces do not
+    # have teams and so you should not specify the team of project in a
+    # regular workspace.
+    class Project < Resource
 
-    alias :create :method_not_allowed
-    alias :destroy :method_not_allowed
+      include EventSubscription
 
-    def self.all_by_task(*args)
-      parent_resources :task
-      all(*args)
-    end
 
-    def self.all_by_workspace(*args)
-      parent_resources :workspace
-      all(*args)
-    end
+      attr_reader :id
 
-    def tasks
-      Task.all_by_project(:params => { :project_id => self.id })
-    end
+      class << self
+        # Returns the plural name of the resource.
+        def plural_name
+          'projects'
+        end
 
-    def modify(modified_fields)
-      resource = Resource.new(modified_fields)
-      response = Project.put(self.id, nil, resource.to_json)
-      Project.new(connection.format.decode(response.body))
-    end
+        # Creates a new project in a workspace or team.
+        #
+        # Every project is required to be created in a specific workspace or
+        # organization, and this cannot be changed once set. Note that you can use
+        # the `workspace` parameter regardless of whether or not it is an
+        # organization.
+        #
+        # If the workspace for your project _is_ an organization, you must also
+        # supply a `team` to share the project with.
+        #
+        # Returns the full record of the newly created project.
+        #
+        # workspace - [Id] The workspace or organization to create the project in.
+        # team - [Id] If creating in an organization, the specific team to create the
+        # project in.
+        #
+        # options - [Hash] the request I/O options.
+        # data - [Hash] the attributes to post.
+        def create(client, workspace: required("workspace"), team: nil, options: {}, **data)
+          with_params = data.merge(workspace: workspace, team: team).reject { |_,v| v.nil? || Array(v).empty? }
+          self.new(parse(client.post("/projects", body: with_params, options: options)).first, client: client)
+        end
+
+        # If the workspace for your project _is_ an organization, you must also
+        # supply a `team` to share the project with.
+        #
+        # Returns the full record of the newly created project.
+        #
+        # workspace - [Id] The workspace or organization to create the project in.
+        # options - [Hash] the request I/O options.
+        # data - [Hash] the attributes to post.
+        def create_in_workspace(client, workspace: required("workspace"), options: {}, **data)
+
+          self.new(parse(client.post("/workspaces/#{workspace}/projects", body: data, options: options)).first, client: client)
+        end
+
+        # Creates a project shared with the given team.
+        #
+        # Returns the full record of the newly created project.
+        #
+        # team - [Id] The team to create the project in.
+        # options - [Hash] the request I/O options.
+        # data - [Hash] the attributes to post.
+        def create_in_team(client, team: required("team"), options: {}, **data)
+
+          self.new(parse(client.post("/teams/#{team}/projects", body: data, options: options)).first, client: client)
+        end
+
+        # Returns the complete project record for a single project.
+        #
+        # id - [Id] The project to get.
+        # options - [Hash] the request I/O options.
+        def find_by_id(client, id, options: {})
 
+          self.new(parse(client.get("/projects/#{id}", options: options)).first, client: client)
+        end
+
+        # Returns the compact project records for some filtered set of projects.
+        # Use one or more of the parameters provided to filter the projects returned.
+        #
+        # workspace - [Id] The workspace or organization to filter projects on.
+        # team - [Id] The team to filter projects on.
+        # archived - [Boolean] Only return projects whose `archived` field takes on the value of
+        # this parameter.
+        #
+        # per_page - [Integer] the number of records to fetch per page.
+        # options - [Hash] the request I/O options.
+        def find_all(client, workspace: nil, team: nil, archived: nil, per_page: 20, options: {})
+          params = { workspace: workspace, team: team, archived: archived, limit: per_page }.reject { |_,v| v.nil? || Array(v).empty? }
+          Collection.new(parse(client.get("/projects", params: params, options: options)), type: self, client: client)
+        end
+
+        # Returns the compact project records for all projects in the workspace.
+        #
+        # workspace - [Id] The workspace or organization to find projects in.
+        # archived - [Boolean] Only return projects whose `archived` field takes on the value of
+        # this parameter.
+        #
+        # per_page - [Integer] the number of records to fetch per page.
+        # options - [Hash] the request I/O options.
+        def find_by_workspace(client, workspace: required("workspace"), archived: nil, per_page: 20, options: {})
+          params = { archived: archived, limit: per_page }.reject { |_,v| v.nil? || Array(v).empty? }
+          Collection.new(parse(client.get("/workspaces/#{workspace}/projects", params: params, options: options)), type: self, client: client)
+        end
+
+        # Returns the compact project records for all projects in the team.
+        #
+        # team - [Id] The team to find projects in.
+        # archived - [Boolean] Only return projects whose `archived` field takes on the value of
+        # this parameter.
+        #
+        # per_page - [Integer] the number of records to fetch per page.
+        # options - [Hash] the request I/O options.
+        def find_by_team(client, team: required("team"), archived: nil, per_page: 20, options: {})
+          params = { archived: archived, limit: per_page }.reject { |_,v| v.nil? || Array(v).empty? }
+          Collection.new(parse(client.get("/teams/#{team}/projects", params: params, options: options)), type: self, client: client)
+        end
+      end
+
+      # A specific, existing project can be updated by making a PUT request on the
+      # URL for that project. Only the fields provided in the `data` block will be
+      # updated; any unspecified fields will remain unchanged.
+      #
+      # When using this method, it is best to specify only those fields you wish
+      # to change, or else you may overwrite changes made by another user since
+      # you last retrieved the task.
+      #
+      # Returns the complete updated project record.
+      #
+      # options - [Hash] the request I/O options.
+      # data - [Hash] the attributes to post.
+      def update(options: {}, **data)
+
+        refresh_with(parse(client.put("/projects/#{id}", body: data, options: options)).first)
+      end
+
+      # A specific, existing project can be deleted by making a DELETE request
+      # on the URL for that project.
+      #
+      # Returns an empty data record.
+      def delete()
+
+        client.delete("/projects/#{id}") && true
+      end
+
+    end
   end
 end

data/lib/asana/resources/registry.rb

@@ -0,0 +1,62 @@
+require 'set'
+
+module Asana
+  module Resources
+    # Internal: Global registry of Resource subclasses. It provides lookup from
+    # singular and plural names to the actual class objects.
+    #
+    # Examples
+    #
+    #   class Unicorn < Asana::Resources::Resource
+    #     path '/unicorns'
+    #   end
+    #
+    #   Registry.lookup(:unicorn) # => Unicorn
+    #   Registry.lookup_many(:unicorns) # => Unicorn
+    #
+    module Registry
+      class << self
+        # Public: Registers a new resource class.
+        #
+        # resource_klass - [Class] the resource class.
+        #
+        # Returns nothing.
+        def register(resource_klass)
+          resources << resource_klass
+        end
+
+        # Public: Looks up a resource class by its singular name.
+        #
+        # singular_name - [#to_s] the name of the resource, e.g :unicorn.
+        #
+        # Returns the resource class or {Asana::Resources::Resource}.
+        def lookup(singular_name)
+          resources.detect do |klass|
+            klass.singular_name.to_s == singular_name.to_s
+          end || Resource
+        end
+
+        # Public: Looks up a resource class by its plural name.
+        #
+        # plural_name - [#to_s] the plural name of the resource, e.g :unicorns.
+        #
+        # Returns the resource class or {Asana::Resources::Resource}.
+        def lookup_many(plural_name)
+          resources.detect do |klass|
+            klass.plural_name.to_s == plural_name.to_s
+          end || Resource
+        end
+
+        # Internal: A set of Resource classes.
+        #
+        # Returns the Set, defaulting to the empty set.
+        #
+        # Note: this object is a mutable singleton, so it should not be accessed
+        # from multiple threads.
+        def resources
+          @resources ||= Set.new
+        end
+      end
+    end
+  end
+end

data/lib/asana/resources/resource.rb

@@ -0,0 +1,103 @@
+require_relative 'registry'
+require_relative 'response_helper'
+
+module Asana
+  module Resources
+    # Public: The base resource class which provides some sugar over common
+    # resource functionality.
+    class Resource
+      include ResponseHelper
+      extend ResponseHelper
+
+      def self.inherited(base)
+        Registry.register(base)
+      end
+
+      def initialize(data, client: required('client'))
+        @_client = client
+        @_data   = data
+        data.each do |k, v|
+          instance_variable_set(:"@#{k}", v) if respond_to?(k)
+        end
+      end
+
+      # If it has findById, it implements #refresh
+      def refresh
+        if self.class.respond_to?(:find_by_id)
+          self.class.find_by_id(client, id)
+        else
+          fail "#{self.class.name} does not respond to #find_by_id"
+        end
+      end
+
+      # Internal: Proxies method calls to the data, wrapping it accordingly and
+      # caching the result by defining a real reader method.
+      #
+      # Returns the value for the requested property.
+      #
+      # Raises a NoMethodError if the property doesn't exist.
+      def method_missing(m, *args)
+        super unless respond_to_missing?(m, *args)
+        cache(m, wrapped(to_h[m.to_s]))
+      end
+
+      # Internal: Guard for the method_missing proxy. Checks if the resource
+      # actually has a specific piece of data at all.
+      #
+      # Returns true if the resource has the property, false otherwise.
+      def respond_to_missing?(m, *)
+        to_h.key?(m.to_s)
+      end
+
+      # Public:
+      # Returns the raw Hash representation of the data.
+      def to_h
+        @_data
+      end
+
+      def to_s
+        attrs = to_h.map { |k, _| "#{k}: #{public_send(k).inspect}" }.join(', ')
+        "#<Asana::#{self.class.name.split('::').last} #{attrs}>"
+      end
+
+      alias_method :inspect, :to_s
+
+      private
+
+      # Internal: The Asana::Client instance.
+      def client # rubocop:disable Style/TrivialAccessors
+        @_client
+      end
+
+      # Internal: Caches a property and a value by defining a reader method for
+      # it.
+      #
+      # property - [#to_s] the property
+      # value    - [Object] the corresponding value
+      #
+      # Returns the value.
+      def cache(property, value)
+        field = :"@#{property}"
+        instance_variable_set(field, value)
+        define_singleton_method(property) { instance_variable_get(field) }
+        value
+      end
+
+      # Internal: Wraps a value in a more useful class if possible, namely a
+      # Resource or a Collection.
+      #
+      # Returns the wrapped value or the plain value if it couldn't be wrapped.
+      def wrapped(value)
+        case value
+        when Hash then Resource.new(value, client: client)
+        when Array then value.map(&method(:wrapped))
+        else value
+        end
+      end
+
+      def refresh_with(data)
+        self.class.new(data, client: @client)
+      end
+    end
+  end
+end