conversocial 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 39314cece44480bb907b43d273ebac7380338506
-  data.tar.gz: e09b7ce8e03411f766bae1c63987517d4dca844a
+  metadata.gz: ef8feb5467b16254c542a01b58fd1001df721499
+  data.tar.gz: a1a4267eeb246cb6a1d6218173c1832fcbda5fe5
 SHA512:
-  metadata.gz: 9430b25701982c8bea259beac69fdcd50b38373269cbef6bab93c24a34009d4ff03f1476909c49e571f076041c1850351f3d57dded34e1844ff0890cc78cecbb
-  data.tar.gz: e441b23bb382487ffd1cb2d26c184ed455baaba1e9e373e25ec9b66d329da10bdc55c7bf2d76fd2b21539e2a6d1d5f5b96c4dbae4cec0a183db449c324d4f64d
+  metadata.gz: c1f31b5dc24413551180556a05c390cc883463247d235d43ff81ba500e8504cbb266ff303bbddf798053a285090e295860426d62799d21cadf5728e5d017ebf4
+  data.tar.gz: 1530913cc3cbbea2d7e72aa190aed25f04df0792ec6ff833b1a662b0d1ce030386073fb20c55cad4606613ae737c5595a673a04c58a443388ee51aa2fe4775bb

data/README.md

@@ -16,44 +16,120 @@ Or install it yourself as:
 
     $ gem install conversocial
 
-## Usage
-
-Disclaimer: I am still working on in depth documentation for this gem. In the meantime, I tried to provide some quick example snippets here.
+## Initialize
 
 Initialize the client with your key and secret
 
     client = Conversocial::Client.new :key => '...', :secret => '...'
 
-And then fetch some data
+## Resources
 
-    client.conversations.limit(3).fetch #note that limit is only supported on conversations
-    client.conversations.where( :status => 'unread' ).fetch
-    client.tags.fetch
-    client.users.fetch
-    client.accounts.fetch
-    client.channels.fetch
-    client.reports.fetch
+Currently, this gem wraps most of the resources exposed by the Conversocial API. You can access these resources via the following query engines on the client object.
+
+    client.accounts
+    client.authors
+    client.channels
+    client.conversations
+    client.reports
+    client.tags
+    client.users
 
-To find a resource by id
+Each of these returns a QueryEngine object for that respective resource with a variety of fetch/find/filter methods that can be chained together to programmatically build richer queries. When a query is executed, it will return a model or an array of models. (See section below for more information on models)
 
+
+## Finding Items
+All of the query engines have a find method which takes an id. Some examples below:
+  
     client.accounts.find 13954
-    client.tags.find 98999
+       => #<Conversocial::Resources::Models::Account(url: https://api.conversocial.com/v1.1/accounts/13954, reports: https://api.conversocial.com/v1.1/reports?account=13954, id: 13954, channels: ["#<Channel(id: 64079)>", "#<Channel(id: 64091)>", "#<Channel(id: 64080)>", "#<Channel(id: 64082)>"], description: My Test Account, package: Enterprise, created_date: 2013-09-24 17:16:06 -0700, name: My Test Account)>
 
-To paginate through all of a certain resource do
+    client.tags.find 25494
+       => #<Conversocial::Resources::Models::Tag(id: 25494, name: Test Tag, url: https://api.conversocial.com/v1.1/tags/25494, is_active: true)>
 
-    client.tags.each_page{ |tags| .... }
-    client.conversations( :status => 'unread' ).each_page{ |conversations| puts "conversation ids on this page are #{conversations.map(&:id).inspect}" }
 
-To get all the conversations for today
 
-    client.conversations.order(:oldest_sort_date).greater_than_or_equal_to(:oldest_sort_date, Date.today ).limit(50).each_page{ |conversations| ... }
+## Fetching Data
+With the exception of authors, all query engines support a fetch method that can be used to return multiple items
+
+    client.tags.fetch
+       => [#<Conversocial::Resources::Models::Tag(id: 25494, name: Tag1, url: https://api.conversocial.com/v1.1/tags/25494, is_active: true)>, #<Conversocial::Resources::Models::Tag(id: 25495, name: Tag2, url: https://api.conversocial.com/v1.1/tags/25495, is_active: true)>, #<Conversocial::Resources::Models::Tag(id: 25496, name: Tag3, url: https://api.conversocial.com/v1.1/tags/25496, is_active: true)>, #<Conversocial::Resources::Models::Tag(id: 25497, name: Tag4, url: https://api.conversocial.com/v1.1/tags/25497, is_active: true)>, #<Conversocial::Resources::Models::Tag(id: 25498, name: Tag5 url: https://api.conversocial.com/v1.1/tags/25498, is_active: true)>, #<Conversocial::Resources::Models::Tag(id: 25499, name: Conversational, url: https://api.conversocial.com/v1.1/tags/25499, is_active: true)>, #<Conversocial::Resources::Models::Tag(id: 25500, name: Tag6, url: https://api.conversocial.com/v1.1/tags/25500, is_active: true)>, #<Conversocial::Resources::Models::Tag(id: 25501, name: Tag7, url: https://api.conversocial.com/v1.1/tags/25501, is_active: true)>, #<Conversocial::Resources::Models::Tag(id: 25502, name: Tag8, url: https://api.conversocial.com/v1.1/tags/25502, is_active: true)>, #<Conversocial::Resources::Models::Tag(id: 25877, name: Tag9, url: https://api.conversocial.com/v1.1/tags/25877, is_active: true)>]
+
+## Filtering
+It is possible to filter your find and fetch queries.
+
+    client.conversations.where( :status => 'unread' ).fetch 
+    client.conversations.where( :status => ['unread', 'archived'] ).fetch
+
+It is possible to chain filters
+
+    client.conversations.where(:status => 'archived').where(:assigned_to => user.id ).fetch
+
+## Comparison Filters
+
+    #get all conversations where oldest sort date is greater than or equal to today
+    client.conversations.greater_than_or_equal_to(:oldest_sort_date, Date.today ).fetch 
+
+    #get all conversations where oldest sort date is greater than today
+    client.conversations.greater_than(:oldest_sort_date, Date.today ).fetch
+
+    #get all conversations where oldest sort date is lesser than or equal to today
+    client.conversations.lesser_than_or_equal_to(:oldest_sort_date, Date.today ).fetch
+
+    #get all conversations where oldest sort date is lesser than today
+    client.conversations.lesser_than(:oldest_sort_date, Date.today ).fetch
+
+## Sorting
+It is possible to sort your queries
 
+    client.conversations.sort(:oldest_sort_date).fetch 
 
+## Limiting
+The only resources that can be limited are conversations.
 
+    client.conversations.limit(4).fetch    #only return up to four conversations
+
+## Selecting
+By default, all fields are selected when you query for resources. However, it is possible to select only a few fields and reduce your api usage.
+
+    conversations.select( 'id', 'status' ).fetch.first
+      => #<Conversocial::Resources::Models::Conversation(id: 5399e4ff0e4b3d76a56e5533, url: not_yet_loaded, status: archived, is_priority: not_yet_loaded, contains_private: not_yet_loaded, tags: not_yet_loaded, author: not_yet_loaded, channels: not_yet_loaded, assigned_to: not_yet_loaded, content_ids: not_yet_loaded, handling_times: not_yet_loaded)>
+
+In the example above, you can see that only the id and status are returned. If for some reason, you decide that you need every field you can call refresh on the returned model. You may be wondering what happens if you attempt to invoke an unloaded field. In this case, the model will automatically refresh itself.
+
+    tag = client.tags.where(:fields => 'id').first
+       => #<Conversocial::Resources::Models::Tag(id: 25494, name: not_yet_loaded, url: https://api.conversocial.com/v1.1/tags/25494, is_active: not_yet_loaded)>
+    tag.refresh
+       => #<Conversocial::Resources::Models::Tag(id: 25494, name: Test Tag, url: https://api.conversocial.com/v1.1/tags/25494, is_active: true)>
+
+
+
+
+## Pagination
+Using the pagination api  is the best way to enumerate through an entire dataset. 
+
+    client.tags.each_page do |tags|
+      tags.each do |tag|
+        puts "processing #{tag.name}"
+      end
+    end
+
+To get all the conversations for today
+
+    client.conversations.greater_than_or_equal_to(:oldest_sort_date, Date.today ).limit(50).each_page do | |conversations|
+      conversations.each do |conversation|
+        puts "processing conversation #{conversation.id}"
+      end
+    end
+
+
+## Future Developments
 Items not yet supported, but that will be in a soon future version
 
-    -saving of reports
-    -the keyvalue resource
+-saving of reports
+
+-the keyvalue resource
+
+-more documentation
 
 ## Contributing
 
@@ -61,4 +137,4 @@ Items not yet supported, but that will be in a soon future version
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request
+5. Create a new Pull Request

data/lib/conversocial/resources/query_engines/base.rb

@@ -100,6 +100,10 @@ module Conversocial
         alias :order :sort
         alias :order_by :sort
 
+        def select *fields
+          where :fields => fields
+        end
+
         def greater_than field, value
           comparison_filter field, "gt", value
         end

data/lib/conversocial/version.rb

@@ -1,3 +1,3 @@
 module Conversocial
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: conversocial
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Misha Conway
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-29 00:00:00.000000000 Z
+date: 2014-09-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler