asana 0.0.6 → 0.1.1

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    YTljM2UwZDM5YWU3ZjQ4MWIwZWRhNjRhYzRhNTQyZjcxYzI5ODg0Zg==
+    ZjVmMmMzNGZiODUxMDA4ODlkODg3NTBhMDNlZTVjYjdmMWU3YjUxYQ==
   data.tar.gz: !binary |-
-    MDNjZGNiZDIyNWE4YzZkYzZkZjk3N2IzODQxZjQ2MmM2ZGRlMWYyYw==
-!binary "U0hBNTEy":
+    ZTI3MWMwYzg5ZDkyNTIzYmUxYmE0NDZmNDJhM2M3ODFmNzdlNGRlYQ==
+SHA512:
   metadata.gz: !binary |-
-    YWEyOTRjYjIzNDc5MjgxZGEyODhjODNkMWJlYTU0MzljYTQxODBiOTNjOGM5
-    OTg5ZDlkODBlYTc4MjZlZjM4ZmE2NTk3MjUxOTM0MWVmZmJlOThmNWExNWY2
-    NTQwNzU2NjNiZTlkZjdiMzdmYzk4NjM3YjRmMjQ5ZGYzM2FiZDM=
+    NDg1YjlmOGQwMjk5MjJmZDllNTc2NDE0ZTQxNWYwYTZlZTg1NWVjYjg4NTRi
+    YTJkMTMyNjYxNjI5NThlMTQ1ZWExZmM2M2MwN2QwYTJmMDQ3NWZiMWE5ZTNl
+    ZmQ2OWYzMGM0ZjMwY2M4NDM4YWQ5NDk0NTYyMDIxMjI1M2VmMzQ=
   data.tar.gz: !binary |-
-    NTY0ZDYzZTRhOGM0MTNhYjgyY2I4NWQ3MGM5YWNlMDMyYzhmZjg3ZWE0NGNj
-    ZjE3ZmNhYmNhNGU4MzgyNDY5YjE3NjVhYjdkMzQzOWFlMTlkNzkzOGFjZjE2
-    ZDYxZTdlNzIxMjE2MjY4MWZiZGE4YTkzMmVkMjc3ZGVlYzAxMmE=
+    MmQ1ZTI4ODRjYjk0MWFiNGMxZWM3ZTkyNDk0OWJkNTk5NzJkMDYxYWFiOTdh
+    ZDEyOGIxZDU5YzQxMjU0NmNlYjJhZDkzZDBkYmY2NGUxMWMyN2FhOGU2MmQ2
+    NzBkYzc1M2EwYWI1MTI5YzhhZmU0MjRiMzY4Nzg1NzVhNjZkZmE=

data/.codeclimate.yml

@@ -0,0 +1,4 @@
+languages:
+  Ruby: true
+exclude_paths:
+- "lib/asana/resources/*"

data/.gitignore

@@ -1,20 +1,12 @@
-*.gem
-*.rbc
-*.un~
-.DS_Store
-.bundle
-.config
-.yardoc
-Gemfile.lock
-InstalledFiles
-_yardoc
-coverage
-doc/
-lib/bundler/man
-pkg
-rdoc
-spec/fixtures/cassettes
-spec/reports
-test/tmp
-test/version_tmp
-tmp
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/bin/
+test.rb
+/node_modules/

data/.rspec

@@ -0,0 +1,4 @@
+--color
+--require spec_helper
+--require asana
+--order random

data/.rubocop.yml

@@ -0,0 +1,18 @@
+AllCops:
+  Include:
+    - '**/Rakefile'
+  Exclude:
+    - 'bin/**/*'
+    - 'examples/**/*'
+    - 'lib/asana/resources/attachment.rb'
+    - 'lib/asana/resources/project.rb'
+    - 'lib/asana/resources/story.rb'
+    - 'lib/asana/resources/tag.rb'
+    - 'lib/asana/resources/task.rb'
+    - 'lib/asana/resources/team.rb'
+    - 'lib/asana/resources/user.rb'
+    - 'lib/asana/resources/workspace.rb'
+    - 'spec/templates/unicorn.rb'
+    - 'spec/templates/world.rb'
+    - 'test.rb'
+require: rubocop-rspec

data/.travis.yml

@@ -0,0 +1,12 @@
+language: ruby
+rvm:
+- 2.2.2
+- 2.0.0
+deploy:
+  provider: rubygems
+  api_key:
+    secure: ZFzExKt6auBOcQyg8955GwlZW2OaS64Q+XHGSay2MzjALw1iiy5uuMdwkueCKrGWSv6/eBe9jjsmYBe3OfkUIpIBbUacnbEYeaC70AyucNjvFrrl0YVYHb7neojarJUmKz9bz9Pkju/jdxksaYaj58xfq5YPQDfjFtdmylvuNEYpujT6goPEbxG4U4PpIhhQOZRDRXXAPS+f7jHejTSK06kvJjiJw0d51VJtBbp+0TKNKL6BDKdOKjKeHuebuUmSw8crDyaYdnwYwmNg1cJrGOv2t76M08zoKkkIO2lwPMHisi1/+cbVcZfxM4SfdHJeU6cQuRdb0uCUbbj6GsGwT8vWP2mGUrLe4UV/GfZDmvK3MKeKIlkgig31a3Qny9yjn8EjSnKHYuHBbJvPQDPPpFUfgEneUxn2t4P6m+epkd1gldWqTWf8mhMR/6xAFT4s+BaxnMMJsTC3Ea+dZZ30EqCw/kx5B2Z1KVLgsxHeMN/Q+AeOcbOvlGDsFL0Mjk/PqDTW1AWKLs/D1ohcxjSmlNJGWR6JHa/Ei0GqjDE2+/ZGsKsRfcDD4kU5qnKdqdzDlbL3cL4tChzuWVcguYdrg1yZzqPrCPzmy+2D7Hphyaj9CPKEh7qwT+IQU5o/V2peOJUjKrMlJS4gFq6MvTDh5U59J88Kkg72DXhcEUcySkU=
+  gem: asana
+  on:
+    tags: true
+    repo: Asana/ruby-asana

data/.yardopts

@@ -0,0 +1,5 @@
+--title "Asana API Ruby Client"
+--readme README.md
+--plugin tomdoc
+lib
+- LICENSE.txt

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http:contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)

data/Gemfile

@@ -2,3 +2,20 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in asana.gemspec
 gemspec
+
+group :tools do
+  gem 'rubocop'
+  gem 'rubocop-rspec'
+
+  gem 'guard'
+  gem 'guard-rspec'
+  gem 'guard-rubocop'
+  gem 'guard-yard'
+
+  gem 'yard'
+  gem 'yard-tomdoc'
+
+  gem 'byebug'
+
+  gem 'simplecov', require: false
+end

data/Guardfile

@@ -1,5 +1,86 @@
-guard 'minitest' do
-  watch(%r|^lib/(.*/)?([^/]+)\.rb$|) { |m| "spec/#{m[1]}#{m[2]}_spec.rb" }
-  watch(%r|^spec/spec_helper\.rb|) { "spec" }
-  watch(%r|^spec/(.*)\/?(.*)_spec\.rb|)
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+## Uncomment and set this to only include directories you want to watch
+# directories %w(app lib config test spec features)
+
+## Uncomment to clear the screen before every task
+# clearing :on
+
+## Guard internally checks for changes in the Guardfile and exits.
+## If you want Guard to automatically start up again, run guard in a
+## shell loop, e.g.:
+##
+##  $ while bundle exec guard; do echo "Restarting Guard..."; done
+##
+## Note: if you are using the `directories` clause above and you are not
+## watching the project directory ('.'), then you will want to move
+## the Guardfile to a watched dir and symlink it back, e.g.
+#
+#  $ mkdir config
+#  $ mv Guardfile config/
+#  $ ln -s config/Guardfile .
+#
+# and, you'll have to watch "config/Guardfile" instead of "Guardfile"
+
+# Note: The cmd option is now required due to the increasing number of ways
+#       rspec may be run, below are examples of the most common uses.
+#  * bundler: 'bundle exec rspec'
+#  * bundler binstubs: 'bin/rspec'
+#  * spring: 'bin/rspec' (This will use spring if running and you have
+#                          installed the spring binstubs per the docs)
+#  * zeus: 'zeus rspec' (requires the server to be started separately)
+#  * 'just' rspec: 'rspec'
+
+guard :rspec, cmd: "bundle exec rspec" do
+  require "guard/rspec/dsl"
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # Feel free to open issues for suggestions and improvements
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  watch(%r{^lib/(.+)\.rb$}) { |m| "spec/#{m[1]}_spec.rb" }
+
+  # Rails files
+  rails = dsl.rails(view_extensions: %w(erb haml slim))
+  dsl.watch_spec_files_for(rails.app_files)
+  dsl.watch_spec_files_for(rails.views)
+
+  watch(rails.controllers) do |m|
+    [
+      rspec.spec.("routing/#{m[1]}_routing"),
+      rspec.spec.("controllers/#{m[1]}_controller"),
+      rspec.spec.("acceptance/#{m[1]}")
+    ]
+  end
+
+  # Rails config changes
+  watch(rails.spec_helper)     { rspec.spec_dir }
+  watch(rails.routes)          { "#{rspec.spec_dir}/routing" }
+  watch(rails.app_controller)  { "#{rspec.spec_dir}/controllers" }
+
+  # Capybara features specs
+  watch(rails.view_dirs)     { |m| rspec.spec.("features/#{m[1]}") }
+
+  # Turnip features and steps
+  watch(%r{^spec/acceptance/(.+)\.feature$})
+  watch(%r{^spec/acceptance/steps/(.+)_steps\.rb$}) do |m|
+    Dir[File.join("**/#{m[1]}.feature")][0] || "spec/acceptance"
+  end
+end
+
+guard :rubocop do
+  watch(%r{.+\.rb$})
+  watch(%r{(?:.+/)?\.rubocop\.yml$}) { |m| File.dirname(m[0]) }
+end
+
+guard 'yard' do
+  watch(%r{app/.+\.rb})
+  watch(%r{lib/.+\.rb})
+  watch(%r{ext/.+\.c})
 end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Asana, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -1,16 +1,23 @@
 # Asana
 
-This gem is a simple Ruby wrapper for the Asana REST API. It uses
-[ActiveResource][] to provide a simple, familiar interface for accessing
-your Asana account.
+[![Build Status](https://travis-ci.org/Asana/ruby-asana.svg)](https://travis-ci.org/Asana/ruby-asana)
+[![Code Climate](https://codeclimate.com/github/Asana/ruby-asana/badges/gpa.svg)](https://codeclimate.com/github/Asana/ruby-asana)
+[![Dependency Status](https://gemnasium.com/Asana/ruby-asana.svg)](https://gemnasium.com/Asana/ruby-asana)
 
-To learn more, check out the [Asana API Documentation][].
+
+A Ruby client for the 1.0 version of the Asana API.
+
+Supported rubies:
+
+* MRI 2.0.0 up to 2.2.x stable
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'asana'
+```ruby
+gem 'ruby-asana'
+```
 
 And then execute:
 
@@ -18,208 +25,330 @@ And then execute:
 
 Or install it yourself as:
 
-    $ gem install asana
+    $ gem install ruby-asana
 
 ## Usage
 
-In order to access Asana, you need to provide your [API key][].
+To do anything, you'll need always an instance of `Asana::Client` configured
+with your preferred authentication method (see the Authentication section below
+for more complex scenarios) and other options.
 
+The most minimal example would be as follows:
 
 ```ruby
-Asana.configure do |client|
-  client.api_key = 'your_asana_api_key'
+require 'asana'
+
+client = Asana::Client.new do |c|
+  c.authentication :api_token, 'my_api_token'
 end
+
+client.workspaces.find_all.first
 ```
 
-As a sanity check, you can fetch the object representing your user.
+A full-blown customized client using OAuth2 wih a previously obtained refresh
+token, Typhoeus as a Faraday adapter, a custom user agent and custom Faraday
+middleware:
 
 ```ruby
-Asana::User.me
+require 'asana'
+
+client = Asana::Client.new do |c|
+  c.authentication :oauth2,
+                   refresh_token: 'abc',
+                   client_id: 'bcd',
+                   client_secret: 'cde',
+                   redirect_uri: 'http://example.org/auth'
+  c.faraday_adapter :typhoeus
+  c.configure_faraday { |conn| conn.use SomeFaradayMiddleware }
+end
+
+workspace = client.workspaces.find_by_id(12)
+workspace.users
+# => #<Asana::Collection<User> ...>
+client.tags.create_in_workspace(workspace: workspace.id, name: 'foo')
+# => #<Asana::Tag id: ..., name: "foo">
 ```
 
-### [Users][]
+All resources are exposed as methods on the `Asana::Client` instance. Check out
+the [documentation for each of them][docs].
+
+### Authentication
 
-> A user object represents an account in Asana that can be given access to
-> various workspaces, projects, and tasks.
-> 
-> Like other objects in the system, users are referred to by numerical IDs.
-> However, the special string identifier me can be used anywhere a user ID is
-> accepted, to refer to the current authenticated user.
+This gem supports authenticating against the Asana API with either an API token or through OAuth2.
 
-**Note:** It is not possible to create, update, or delete a user from
-the API.
+#### API Token
 
 ```ruby
-# Get users from all of your workspaces
-users = Asana::User.all
+Asana::Client.new do |c|
+  c.authentication :api_token, 'my_api_token'
+end
+```
 
-# Get a specific user
-user = Asana::User.find(:user_id)
+#### OAuth2
 
-# Get the user associated with the API key being used
-user = Asana::User.me
+Authenticating through OAuth2 is preferred. There are many ways you can do this.
 
-# Get all users in a given workspace
-workspace = Asana::Workspace.find(:workspace_id)
-users = workspace.users
-```
+##### With a plain bearer token (doesn't support auto-refresh)
 
-### [Workspaces][]
+If you have a plain bearer token obtained somewhere else and you don't mind not
+having your token auto-refresh, you can authenticate with it as follows:
 
-> A workspace is the most basic organizational unit in Asana. All projects
-> and tasks have an associated workspace.
+```ruby
+Asana::Client.new do |c|
+  c.authentication :oauth2, bearer_token: 'my_bearer_token'
+end
+```
 
-**Note:** It is not possible to create or delete a workspace from the API.
+##### With a refresh token and client credentials
+
+If you obtained a refresh token, you can use it together with your client
+credentials to authenticate:
 
 ```ruby
-# Get all workspaces
-workspaces = Asana::Workspace.all
+Asana::Client.new do |c|
+  c.authentication :oauth2,
+                   refresh_token: 'abc',
+                   client_id: 'bcd',
+                   client_secret: 'cde',
+                   redirect_uri: 'http://example.org/auth'
+end
+```
 
-# Get a specific workspace
-workspace = Asana::Workspace.find(:workspace_id)
+##### With an ::OAuth2::AccessToken object (from `omniauth-asana` for example)
 
-# Get all projects in a given workspace
-projects = workspace.projects
+If you use `omniauth-asana` or a browser-based OAuth2 authentication strategy in
+general, possibly because your application is a web application, you can reuse
+those credentials to authenticate with this API client. Here's how to do it from
+the callback method:
 
-# Get all tasks in a given workspace that are assigned to the given user
-tasks = workspace.tasks(:user_id)
+```ruby
+# assuming we're using Sinatra and omniauth-asana
+get '/auth/:name/callback' do
+  creds = request.env["omniauth.auth"]["credentials"].tap { |h| h.delete('expires') }
+  strategy = request.env["omniauth.strategy"]
+
+  # We need to refresh the omniauth OAuth2 token
+  access_token = OAuth2::AccessToken.from_hash(strategy.client, creds).refresh!
+
+  $client = Asana::Client.new do |c|
+    c.authentication :oauth2, access_token
+  end
+ 
+  redirect '/'
+end
+```
 
-# Get all users with access to a given workspace
-users = workspace.users
+See `examples/omniauth_integration.rb` for a working example of this.
 
-# Get all tags in a given workspace
-tags = workspace.tags
+##### Using an OAuth2 offline authentication flow (for CLI applications)
 
-# Create a new task in a given workspace and assign it to the current user
-workspace.create_task(:name => 'Get milk from the grocery store')
+If your application can't receive HTTP requests and thus you can't use
+`omniauth-asana`, for example if it's a CLI application, you can authenticate as
+follows:
 
-# Create a new project in a given workspace, current user as a watcher
-workspace.create_project(:name => 'Upgrade Asana gem')
+```ruby
+access_token = Asana::Authentication::OAuth2.offline_flow(client_id: ...,
+                                                          client_secret: ...)
+client = Asana::Client.new do |c|
+  c.authentication :oauth2, access_token
+end
 
-# Create a new tag in a given workspace
-workspace.create_tag(:name => 'Programming')
+client.tasks.find_by_id(12)
 ```
 
-### [Projects][]
+This will print an authorization URL on STDOUT, and block until you paste in the
+authorization code, which you can get by visiting that URL and granting the
+necessary permissions.
 
-> A project represents a prioritized list of tasks in Asana. It exists in a
-> single workspace and is accessible to a subset of users in that workspace
-> depending on its permissions.
+### Pagination
 
-**Note:** It is not possible to create or delete a project from the API.
+Whenever you ask for a collection of resources, you can provide a number of
+results per page to fetch, between 1 and 100. If you don't provide any, it
+defaults to 20.
 
 ```ruby
-# Get all projects
-projects = Asana::Project.all
+my_tasks = client.tasks.find_by_tag(tag: tag_id, per_page: 5)
+# => #<Asana::Collection<Task> ...>
+```
+
+An `Asana::Collection` is a paginated collection -- it holds the first
+`per_page` results, and a reference to the next page if any.
 
-# Get a specific project
-project = Asana::Project.find(:project_id)
+When you iterate an `Asana::Collection`, it'll transparently keep fetching all
+the pages, and caching them along the way:
 
-# Get all projects in a given workspace
-workspace = Asana::Workspace.find(:workspace_id)
-projects = workspace.projects
+```ruby
+my_tasks.size # => 23, not 5
+my_tasks.take(14)
+# => [#<Asana::Task ...>, #<Asana::Task ...>, ... until 14]
+```
 
-# Change the name of a project
-project.modify(:name => 'New project name')
+#### Manual pagination
+
+If you only want to deal with one page at a time and manually paginate, you can
+get the elements of the current page with `#elements` and ask for the next page
+with `#next_page`, which will return an `Asana::Collection` with the next page
+of elements:
+
+```ruby
+my_tasks.elements # => [#<Asana::Task ...>, #<Asana::Task ...>, ... until 5]
+my_tasks.next_page # => #<Asana::Collection ...>
 ```
 
-### [Tasks][]
+#### Lazy pagination
 
-> The task is the basic object around which many operations in Asana are
-> centered. In the Asana application, multiple tasks populate the middle
-> pane according to some view parameters, and the set of selected tasks
-> determine the more detailed information presented in the details pane.
+Because an `Asana::Collection` represents the entire collection, it is often
+handy to just take what you need from it, rather than let it fetch all its
+contents from the network. You can accomplish this by turning it into a lazy
+collection with `#lazy`:
 
 ```ruby
-# Get all tasks in a given project
-project = Asana::Project.find(:project_id)
-tasks = project.tasks
+# let my_tasks be an Asana::Collection of 10 pages of 100 elements each
+my_tasks.lazy.drop(120).take(15).to_a
+# Fetches only 2 pages, enough to get elements 120 to 135
+# => [#<Asana::Task ...>, #<Asana::Task ...>, ...]
+```
 
-# Get all tasks in a given workspace
-workspace = Asana::Workspace.find(:workspace_id)
-tasks = workspace.tasks
+### Error handling
 
-# Get all tasks with a given tag
-tag = Asana::Tag.find(:tag_id)
-tasks = tag.tasks
+In any request against the Asana API, there a number of errors that could
+arise. Those are well documented in the [Asana API Documentation][apidocs], and
+are represented as exceptions under the namespace `Asana::Errors`.
 
-# Get all stories for a given task
-task = tasks.first
-stories = task.stories
+All errors are subclasses of `Asana::Errors::APIError`, so make sure to rescue
+instances of this class if you want to handle them yourself.
 
-# Create a new task in a given workspace and assign it to the current user
-workspace.create_task(:name => 'Get milk from the grocery store')
+### I/O options
 
-# Create a new story for the given task
-task.create_story(story_settings)
+All requests (except `DELETE`) accept extra I/O options
+[as documented in the API docs][io]. Just pass an extra `options` hash to any
+request:
 
-# Add a project to the task (tasks can be in multiple projects)
-task.add_project(project.id)
+```ruby
+client.tasks.find_by_id(12, options: { expand: ['workspace'] })
 ```
 
-### [Tags][]
+### Attachment uploading
 
-> A tag is a label that can be attached to any task in Asana. It exists in
-> a single workspace or organization.
->
-> Tags have some metadata associated with them, but it is possible that we will
-> simplify them in the future so it is not encouraged to rely too heavily on
-> it. Unlike projects, tags do not provide any ordering on the tasks they are
-> associated with.
+To attach a file to a task or a project, you just need its absolute path on your
+filesystem and its MIME type, and the file will be uploaded for you:
 
 ```ruby
-# Get all tags in a given workspace
-workspace = Asana::Workspace.find(:workspace_id)
-tags = workspace.tags
+task = client.tasks.find_by_id(12)
+attachment = task.attach(filename: '/absolute/path/to/my/file.png',
+                         mime: 'image/png')
+attachment.name # => 'file.png'
+```
+
+### Event streams
 
-# Get all tasks with a given tag
-tag = Asana::Tag.find(:tag_id)
-tasks = tag.tasks
+To subscribe to an event stream of a task or a project, just call `#events` on
+it:
 
-# Create a new tag in a given workspace
-workspace.create_tag(:name => 'Programming')
+```ruby
+task = client.tasks.find_by_id(12)
+task.events # => #<Asana::Events ...>
 
-# Update a tag
-tag = Asana::Tag.find(:tag_id)
-tag.modify(:name => 'Development')
+# You can do the same with only the task id:
+events = client.events.for(task.id)
 ```
 
-### [Stories][]
+An `Asana::Events` object is an infinite collection of `Asana::Event`
+instances. Be warned that if you call `#each` on it, it will block forever!
+
+Note that, by default, an event stream will wait at least 1 second between
+polls, but that's configurable with the `wait` parameter:
+
+```ruby
+# wait at least 3 and a half seconds between each poll to the API
+task.events(wait: 3.5) # => #<Asana::Events ...>
+```
 
-> A story represents an activity associated with an object in the Asana
-> system. Stories are generated by the system whenever users take actions
-> such as creating or assigning tasks, or moving tasks between projects.
-> Comments are also a form of user-generated story.
+There are some interesting things you can do with an event stream, as it is a
+normal Ruby Enumerable. Read below to get some ideas.
 
-**Note:** It is not possible to update or delete a story from the API.
+#### Subscribe to the event stream with a callback, polling every 2 seconds
 
 ```ruby
-# Get all stories for a given task
-project = Asana::Project.find(:project_id)
-task = project.tasks.first
-stories = task.stories
+# Run this in another thread so that we don't block forever
+events = client.tasks.find_by_id(12).events(wait: 2)
+Thread.new do
+  events.each do |event|
+    notify_someone "New event arrived! #{event}"
+  end
+end
+```
+
+#### Make the stream lazy and filter it by a specific pattern
 
-# Get a specific story
-story = Story.find(:story_id)
+To do that we need to call `#lazy` on the `Events` instance, just like with any
+other `Enumerable`.
 
-# Create a new story for the given task/project
-task.create_story(story_settings)
+```ruby
+events = client.tasks.find_by_id(12).events
+only_change_events = events.lazy.select { |event| event.action == 'changed' }
+Thread.new do
+  only_change_events.each do |event|
+    notify_someone "New change event arrived! #{event}"
+  end
+end
 ```
 
+## Development
+
+You'll need Ruby 2.1+ and Node v0.10.26+ / NPM 1.4.3+ installed.
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`bin/console` for an interactive prompt that will allow you to experiment.
+
+Run the build with `rake`. This is equivalent to:
+
+    $ rake spec && rake rubocop && rake yard
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Releasing a new version
+
+To release a new version, run either of these commands:
+
+    rake bump:patch
+    rake bump:minor
+    rake bump:major
+
+This will: update `lib/asana/version.rb`, commit and tag the commit. Then you
+just need to `push --tags` to let Travis build and release the new version to
+Rubygems:
+
+    git push --tags
+
+### Code generation
+
+The specific Asana resource classes (`Tag`, `Workspace`, `Task`, etc) are
+generated code, hence they shouldn't be modified by hand. The code that
+generates it lives in `lib/templates/resource.ejs`, and is tested by generating
+`spec/templates/unicorn.rb` and running `spec/templates/unicorn_spec.rb` as part
+of the build.
+
+If you wish to make changes on the code generation script:
+
+1. Add/modify a spec on `spec/templates/unicorn_spec.rb`
+2. Add your new feature or change to `lib/templates/resource.ejs`
+3. Run `rake` or, more granularly, `rake codegen && rspec
+   spec/templates/unicorn_spec.rb`
+
+Once you're sure your code works, submit a pull request and ask the maintainer
+to make a release, as they'll need to run a release script from the
+[asana-api-meta][meta] repository.
+
 ## Contributing
 
-1. Fork it
+1. Fork it ( https://github.com/[my-github-username]/asana/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Added some feature'`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
-
-[API key]: http://app.asana.com/-/account_api
-[ActiveResource]: http://api.rubyonrails.org/classes/ActiveResource/Base.html
-[Asana API Documentation]: http://developer.asana.com/documentation/
-[Users]: http://developer.asana.com/documentation/#users
-[Workspaces]: http://developer.asana.com/documentation/#workspaces
-[Projects]: http://developer.asana.com/documentation/#projects
-[Tasks]: http://developer.asana.com/documentation/#tasks
-[Stories]: http://developer.asana.com/documentation/#stories
-[Tags]: http://developer.asana.com/documentation/#tags
+5. Create a new Pull Request
+
+[apidocs]: https://asana.com/developers
+[io]: https://asana.com/developers/documentation/getting-started/input-output-options
+[docs]: https://asana.github.com/ruby-asana
+[meta]: https://github.com/asana/asana-api-meta