contextio 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 028f4ed25415c6d3512c35374b324199b18131e6
-  data.tar.gz: 4369526ee522539a85b89ea065523c1b7f0ce4a4
+  metadata.gz: f3726a18eda9fc6ebe4ca26a055cefc0ab8c21c6
+  data.tar.gz: 70f0f22c3c52460d4e81648f2839c05e5f88514f
 SHA512:
-  metadata.gz: edce3fb7fe4a13c6e1388cc41e2f0369de581553cc3453ca84b2b239693ca4066fa06d8a7edb216cfee24d0614af509c1c47af22c9fe224b5406732e30776620
-  data.tar.gz: 5a024a9a50af47dec49a6dd032e288032af1b1dcd06e5f28e9b2d863e2c15785550d148a2b7fbd87ebad856568ee065e5cb78acaedfe622ceebbbfc5bfdbe487
+  metadata.gz: 2651ef5e3d6ea6276eaaebf33761120b9e68b42be0a35e8a2cdbe5d8b04481bd1dd55b857b65ec265f601c48c07d3004b4d66e346401553b0b202c22fc57cee5
+  data.tar.gz: 6258631b9b65b5b624fbb545d8175b768997f84b10268fa05bc31617b2bba921f486934ae469bdb537874f273d27069a79a01c169379a403e1218671b894c0fa

data/CHANGES.md

@@ -1,5 +1,16 @@
 # Changes
 
+## 1.6.0
+
+* Add `version` and `base_url` instance variables to API. - Dominik Gehl
+* Don't try to JSON parse raw attachments. - Dominik Gehl
+* Use symbols for options internally to avoid OAuth gem failure. - Ben Hamill
+* Add `in_reply_to` to `Message`'s lazy attributes. - Asa Wilson
+* Fix bug where `Hash`es with mixed `String`/`Symbol` keys would cause the OAuth
+  gem to explode. - Ben Hamill
+* Add missing files association to `Message` class. - Ben Hamill
+* Add a ton of examples to the README to help new users. - Johnny Goodman
+
 ## 1.5.0
 
 * Make `Source#sync!` and `Account#sync!` take an options hash that will be

data/README.md

@@ -3,6 +3,7 @@
 * [Homepage](https://github.com/contextio/contextio-ruby#readme)
 * [API Documentation](http://context.io/docs/2.0/)
 * [Gem Documentation](http://rubydoc.info/gems/contextio/frames)
+* [API Explorer](https://console.context.io/#explore)
 * [Sign Up](http://context.io)
 
 
@@ -11,8 +12,17 @@
 Provides a Ruby interface to [Context.IO](http://context.io). The general design
 was inspired by the wonderful [aws-sdk](https://github.com/aws/aws-sdk-ruby)
 gem. You start with an object that represents your account with Context.IO and
-then you deal with collections within that going forward (see the [Usage
-section](#usage)).
+then you deal with collections within that going forward (see the [Quick Start
+section](#quick start)).
+
+
+## Install
+
+    $ gem install contextio
+
+Or, of course, put this in your Gemfile:
+
+    gem 'contextio'
 
 
 ## A Note On Method Names
@@ -28,15 +38,6 @@ docs](http://rubydoc.info/gems/contextio/frames) for a specific class when in
 doubt.
 
 
-## Install
-
-    $ gem install contextio
-
-Or, of course, put this in your Gemfile:
-
-    gem 'contextio'
-
-
 ## Version Numbers
 
 This gem adheres to [SemVer](http://semver.org/). So you should be pretty safe
@@ -45,7 +46,11 @@ bump. When the major version bumps, be warned; upgrading will take some kind of
 effort.
 
 
-## Usage
+## Examples
+
+### Quick Start
+
+Print the subject of the first five messages in the some@email.com account.
 
 ```ruby
 require 'contextio'
@@ -54,29 +59,254 @@ contextio = ContextIO.new('your_api_key', 'your_api_secret')
 
 account = contextio.accounts.where(email: 'some@email.com').first
 
-account.email_addresses # ['some@email.com', 'another@email.com']
-account.first_name # 'Bruno'
-account.suspended? # False
-
-account.messages.where(folder: '\Drafts').each do |m|
-  puts m.subject
+account.messages.where(limit: 5).each do |message|
+  puts message.subject
 end
 ```
 
+
+### Primary Key Queries
+
 To grab some object you already know the primary key for, you'll use the `[]`
-method like you would for a `Hash` or `Array`. This is most helpful for
-accounts, but works for any resource collection.
+method like you would for a `Hash` or `Array`.
+
+This is most helpful for accounts, but works for any resource collection.
 
 ```ruby
 require 'contextio'
 
 contextio = ContextIO.new('your_api_key', 'your_api_secret')
 
+some_account_id = "exampleaccountid12345678"
+
 account = contextio.accounts[some_account_id]
 message = account.messages[some_message_id]
 ```
 
 
+#### Message By Key
+
+```ruby
+message = account.messages[some_message_id]
+
+message.message_id    #=> "examplemessageid12345678"
+message.subject       #=> "My Email's Subject"
+message.from.class    #=> Hash
+message.from['email'] #=> "some@email.com"
+message.from['name']  #=> "John Doe"
+
+message.delete #=> true
+```
+
+Body content must be accessed through each body part (eg: html, text, etc.).
+Context.io does not store body content and so each call will source it
+directly from the mail box associated with the account. This will be slow
+relative to the context.io API.
+
+You can specify and receive a single body content type.
+
+```ruby
+message = account.messages[some_message_id]
+
+message_part = message.body_parts.where(type: 'text/plain').first
+
+message_part.class    #=> ContextIO::BodyPart
+message_part.type     #=> "text/plain"
+message_part.content  #=> "body content of text/plain body_part"
+```
+
+You can determine how many body parts are available and iterate over each one.
+
+```ruby
+message = account.messages[some_message_id]
+
+message.body_parts.class #=> ContextIO::BodyPartCollection
+message.body_parts.count #=> 2
+
+message.body_parts.each do |part|
+  puts part.class   #=> ContextIO::BodyPart
+  puts part.type    #=> "text/html"
+  puts part.content #=> "body content of text/html body_part"
+end
+```
+
+
+#### Account By Key
+
+You can specify an account id and get back information about that account.
+
+```ruby
+account = contextio.accounts[some_account_id]
+
+account.email_addresses #=> ['some@email.com', 'another@email.com']
+account.id              #=> "exampleaccountid12345678"
+account.first_name      #=> "Bruno"
+account.suspended?      #=> False
+```
+
+
+### Message Collections
+
+#### Query Basics
+
+Queries to Messages return ContextIO::MessageCollection objects which can be
+iterated on.
+
+The `where` method allows you to refine search results based on
+[available filters](http://context.io/docs/2.0/accounts/messages#get).
+
+```ruby
+#the 25 most recent messages by default, you can specify a higher limit
+account.messages
+
+#the 50 most recent messages
+account.messages.where(limit: 50)
+
+#recent messages sent to the account by some@email.com
+account.messages.where(from: 'some@email.com')
+
+#multiple parameters accepted in hash format
+account.messages.where(from: 'some@email.com', subject: 'hello')
+
+#regexp accepted as a string like '/regexp/'
+account.messages.where(from: 'some@email.com', subject: '/h.llo/')
+
+#regexp options are supported, the /i case insensitive is often useful
+account.messages.where(from: 'some@email.com', subject: '/h.llo/i')
+```
+
+
+#### Querying Dates
+
+Pass dates in to message queries as Unix Epoch integers.
+
+```ruby
+require 'active_support/all'
+
+account.messages.where(date_before: 3.hours.ago.to_i, date_after: 5.hours.ago.to_i).each do |message|
+  puts "(#{message.date}) #{message.subject}"
+end
+```
+
+You can mix date and non-date parameters.
+
+```ruby
+account.messages.where(
+  date_before: 3.days.ago.to_i,
+  date_after: 4.weeks.ago.to_i,
+  subject: 'subject of email',
+  from: 'foo@email.com'
+)
+```
+
+
+### Individual Messages
+
+#### Message Basics
+
+```ruby
+account.messages.where(limit: 1).class # ContextIO::MessageCollection
+
+message = account.messages.where(limit: 1).first
+
+message.class   #=> ContextIO::Message
+message.subject #=> "subject of message"
+message.from    #=> {"email"=>"some@email.com", "name"=>"John Doe"}
+message.to      #=> [{"email"=>"some@email.com", "name"=>"'John Doe'"}, {"email"=>"another@email.com", "name"=>"Jeff Mangum"}]
+```
+
+#### Message Dates
+
+##### received_at
+
+`received_at` is the time when your IMAP account records the message
+having arrived. It is returned as a Time object.
+
+```ruby
+m.received_at       #=> 2013-04-19 08:12:04 -0500
+m.received_at.class #=> Time
+```
+
+##### indexed_at
+
+`indexed_at` is the time when the message was processed and indexed
+by the Context.io sync process.
+
+```ruby
+m.indexed_at        #=> 2013-04-29 01:14:39 -0500
+m.received_at.class #=> Time
+```
+
+##### date
+
+A message's date is set by the sender, extracted from the message's Date
+header and is returned as a FixNum which can be converted into a Time
+object.
+
+```ruby
+message.date                #=> 1361828599
+Time.at(message.date)       #=> 2013-04-19 08:11:33 -0500
+Time.at(message.date).class #=> Time
+```
+
+`message.date` is not reliable as it is easily spoofed. While it is made
+available, `received_at` and `indexed_at` are better choices.
+
+
+#### Messages with Body Data
+
+By default, Context.io's API does not return message queries with body data.
+
+You can include the body attribute in each individual message returned by
+adding `include_body: 1` to your `messages.where` query options.
+
+```ruby
+account.messages.where(include_body: 1, limit: 1).each do |message|
+  puts "#{message.subject} #{message.date} #{message.body[0]['content']}"
+end
+```
+
+Emails that contain two or more body parts are called [multipart messages](https://en.wikipedia.org/wiki/MIME#Alternative).
+
+'text/plain' and 'text/html' are common body part types for multipart
+messages.
+
+In the case a user is viewing email in a client that does not support HTML
+markup, the 'text/plain' body part type will render instead.
+
+If you are working with multipart messages, you may want to check each
+body part's content in turn.
+
+```ruby
+account.messages.where(include_body: 1, limit: 1).each do |message|
+  message.body_parts.each do |body_part|
+    puts body_part.content
+  end
+end
+```
+
+The `include_body` method queries the source IMAP box directly, which results
+in slower return times.
+
+
+### Files
+
+#### Files Per Message ID
+
+```ruby
+message = account.messages[message_id]
+
+message.files.class                   #=> ContextIO::FileCollection
+message.files.count                   #=> 2
+message.files.map { |f| f.file_name } #=> ["at_icon.png", "argyle_slides.png"]
+message.files.first.resource_url      #=> https://contextio_to_s3_redirect_url.io
+```
+
+The file['resource_url'] url is a S3 backed temporary link. It is intended
+to be used promptly after being called. Do not store off this link. Instead,
+store off the message_id and request on demand.
+
+
 ### On Laziness
 
 This gem is architected to be as lazy as possible. It won't make an HTTP request
@@ -88,7 +318,7 @@ require 'contextio'
 
 contextio = ContextIO.new('your_api_key', 'your_api_secret')
 
-account = contextio.accounts['1234'] # No request made here.
+account = contextio.accounts['exampleaccountid12345678'] # No request made here.
 account.last_name # Request made here.
 account.first_name # No request made here.
 ```
@@ -101,8 +331,8 @@ docs](http://rubydoc.info/gems/contextio/frames) will trigger the request.
 
 ### On Requests and Methods
 
-There are some consistent mappings between the requests documented in the [API
-docs](http://context.io/docs/2.0/) and the methods implemented in the gem.
+There are some consistent mappings between the requests documented in the
+[API docs](http://context.io/docs/2.0/) and the methods implemented in the gem.
 
 **For collections of resources:**
 
@@ -143,6 +373,6 @@ failing test can be helpful. If in doubt, make an Issue to discuss.
 
 ## Copyright
 
-Copyright (c) 2012 Context.IO
+Copyright (c) 2012-2013 Context.IO
 
 This gem is distributed under the MIT License. See LICENSE.md for details.

data/contextio.gemspec

@@ -21,7 +21,7 @@ Gem::Specification.new do |gem|
 
   gem.add_development_dependency 'bundler'
   gem.add_development_dependency 'rubygems-tasks',  '~> 0.2'
-  gem.add_development_dependency 'rspec',           '~> 2.4'
+  gem.add_development_dependency 'rspec',           '~> 2.14'
   gem.add_development_dependency 'rake'
   gem.add_development_dependency 'yard'
   gem.add_development_dependency 'redcarpet'

data/lib/contextio/api.rb

@@ -52,6 +52,8 @@ class ContextIO
       self.class.user_agent_string
     end
 
+    attr_accessor :base_url, :version
+
     # @!attribute [r] key
     #   @return [String] The OAuth key for the user's Context.IO account.
     # @!attribute [r] secret
@@ -67,6 +69,8 @@ class ContextIO
       @key = key
       @secret = secret
       @opts = opts || {}
+      @base_url = self.class.base_url
+      @version = self.class.version
     end
 
     # Generates the path for a resource_path and params hash for use with the API.
@@ -76,7 +80,7 @@ class ContextIO
     # @param [{String, Symbol => String, Symbol, Array<String, Symbol>}] params
     #   A Hash of the query parameters for the action represented by this path.
     def path(resource_path, params = {})
-      "/#{API.version}/#{API.strip_resource_path(resource_path)}#{API.hash_to_url_params(params)}"
+      "/#{version}/#{strip_resource_path(resource_path)}#{API.hash_to_url_params(params)}"
     end
 
     # Makes a request against the Context.IO API.
@@ -129,15 +133,19 @@ class ContextIO
     # @return [Net::HTTP*] The response object from the request.
     def oauth_request(method, resource_path, params, headers=nil)
       headers ||= { 'Accept' => 'application/json', 'User-Agent' => user_agent_string }
+      normalized_params = params.inject({}) do |normalized_params, (key, value)|
+        normalized_params[key.to_sym] = value
+        normalized_params
+      end
 
       # The below array used to include put, too, but there is a weirdness in
       # the oauth gem with PUT and signing requests. See
       # https://github.com/oauth/oauth-ruby/pull/34#issuecomment-5862199 for
       # some discussion on the matter. This is a work-around.
       if %w(post).include? method.to_s.downcase
-        token.request(method, path(resource_path), params, headers)
+        token.request(method, path(resource_path), normalized_params, headers)
       else # GET, DELETE, HEAD, etc.
-        token.request(method, path(resource_path, params), nil, headers)
+        token.request(method, path(resource_path, normalized_params), nil, headers)
       end
     end
 
@@ -147,7 +155,7 @@ class ContextIO
     # @param [#to_s] resource_path The full URL or path for a resource.
     #
     # @return [String] The resource path.
-    def self.strip_resource_path(resource_path)
+    def strip_resource_path(resource_path)
       resource_path.to_s.gsub("#{base_url}/#{version}/", '')
     end
 
@@ -175,7 +183,7 @@ class ContextIO
     # @return [OAuth::Consumer] An Oauth consumer object for credentials
     #   purposes.
     def consumer
-      @consumer ||= OAuth::Consumer.new(key, secret, @opts.merge(site: API.base_url))
+      @consumer ||= OAuth::Consumer.new(key, secret, @opts.merge(site: base_url))
     end
 
     # @!attribute [r] token

data/lib/contextio/file.rb

@@ -48,7 +48,7 @@ class ContextIO
     end
 
     def content
-      @content ||= api.request(:get, "#{resource_url}/content")
+      @content ||= api.raw_request(:get, "#{resource_url}/content")
     end
 
     def content_link