README.md in etsy-0.2.1 vs README.md in etsy-0.2.2

@@ -1,8 +1,9 @@
 # Etsy
 
 [![Build Status](https://secure.travis-ci.org/kytrinyx/etsy.png)](http://travis-ci.org/kytrinyx/etsy)
+[![Dependency Status](https://gemnasium.com/kytrinyx/etsy.png)](https://gemnasium.com/kytrinyx/etsy)
 
 ## Description
 
 The Etsy gem provides a friendly Ruby interface to the Etsy API
 
@@ -12,13 +13,13 @@
 
     $ gem install etsy
 
 If you want to be on the bleeding edge, install from GitHub:
 
-    $ git clone git://github.com/reagent/etsy.git
+    $ git clone git://github.com/kytrinyx/etsy.git
     $ cd etsy
-    $ rake gem && gem install pkg/etsy-<version>.gem
+    $ rake install
 
 ### Dependencies
 
 The gem has been verified to work with version 1.5.0 of json.
 It will likely work with higher versions, but this is unproven.
@@ -219,10 +220,68 @@
 If you want a more fine-grained response, you can specify the associations as an array of hashes, each of which must contain the name of the resource, and can also include the fields you wish returned, as well as the limit and offset.
 
     >> association = {:resource => 'Images', :fields => ['red','green','blue'], :limit => 1, :offset => 0}
     >> Listing.find(1, {:includes => [association]})
 
+## Public mode vs authenticated calls
+
+This additional example should make clear the difference between issuing public versus authenticated requests: 
+
+### Public workflow
+
+    >> Etsy.api_key = 'key'
+	>> user = Etsy.user('user_id_or_name')
+	>> Etsy::Listing.find_all_by_shop_id(user.shop.id, :limit => 5)
+
+### Authenticated workflow
+
+    >> Etsy.api_key = 'key'
+	>> Etsy.api_secret = 'secret'
+    >> user = Etsy.myself(token, secret)
+	>> access = { :access_token => user.token, :access_secret => user.secret }
+	>> Etsy::Listing.find_all_by_shop_id(user.shop.id, access.merge(:limit => 5))
+	
+## Error handling
+
+Next versions of this gem will raise errors when requests are unsuccessful. The current version does not. 
+Use either of following workarounds:
+
+### Low-level API
+
+Instead of doing this:
+
+    >> Etsy::Request.get('/users/__SELF__', access).result 
+
+Write this:
+
+    >> Etsy::Request.get('/users/__SELF__', access).to_hash["results"]
+
+### Monkey patch
+
+This is Ruby, reopen the <code>Response</code> class anywhere in your codebase and redefine <code>result</code>:
+
+      class Etsy::Response
+        def result
+	      if success?
+	        results = to_hash['results'] || []
+	        count == 1 ? results.first : results
+	      else
+	       validate!
+	      end
+        end
+      end
+
+### Usage
+
+With the above in place, you can now rescue errors and act upon them:
+
+      begin
+        Etsy.myself(access.token, access.secret)		
+      rescue Etsy::OAuthTokenRevoked, Etsy::InvalidUserID, Etsy::MissingShopID, Etsy::EtsyJSONInvalid, Etsy::TemporaryIssue => e
+        puts e.message
+      end 
+
 ## Contributing
 
 I have a "commit bit" policy for contributions to this repository. Once I accept
 your patch, I will give you full commit access.  To submit patches:
 
@@ -237,11 +296,11 @@
     # Setup the project
     git clone kytrinyx/etsy
     git fork
     bundle
     rake
-    
+
     # Normal flow
     git checkout -b your-feature-or-bug
     # Write your tests
     # Make the tests pass
     git add <CHANGES>
@@ -260,10 +319,11 @@
 * [Matt Fields](https://github.com/mfields106)
 * [Jake Boxer](https://github.com/jakeboxer)
 * [Trae Robrock](https://github.com/trobrock)
 * [Jimmy Tang](https://github.com/jimmytang)
 * [Julio Santos](https://github.com/julio)
+* [Roger Smith](https://github.com/rogsmith)
 
 ### Github Flow
 
 For those of you with commit access, please check out Scott Chacon's blog post about [github flow](http://scottchacon.com/2011/08/31/github-flow.html)
 
@@ -274,27 +334,6 @@
 > * After someone else has reviewed and signed off on the feature, you can merge it into master
 > * Once it is merged and pushed to ‘master’, you can and should deploy immediately
 
 ## License
 
-Copyright (c) 2009 - 2012 Patrick Reagan ([e-mail])
-
-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.
+The Etsy rubygem is released under the MIT license.