context-io 0.0.1

data/Gemfile

@@ -0,0 +1,4 @@
+source :rubygems
+
+gemspec
+

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) Henrik Hodne
+
+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

@@ -0,0 +1,129 @@
+ContextIO - Extract data from email
+===================================
+
+[![Build Status](https://secure.travis-ci.org/dvyjones/context-io.png)](http://travis-ci.org/dvyjones/context-io)
+[![Dependency Status](https://gemnasium.com/dvyjones/context-io.png)](https://gemnasium.com/dvyjones/context-io)
+
+## Description
+
+ContextIO is a Ruby wrapper for the [Context.IO][contextio] web service.
+
+Context.IO is the missing email API that makes it easy and fast
+to integrate your user's email data in your application.
+
+ContextIO follows the rules of [Semantic Versioning][semver] and uses
+[TomDoc][tomdoc] for inline documentation.
+
+[contextio]: http://context.io
+[semver]: http://semver.org
+[tomdoc]: http://tomdoc.org
+
+
+## Installation
+
+The best way to install ContextIO is through Rubygems:
+
+```
+$ [sudo] gem install context-io
+```
+
+If you're installing from source, you can use [Bundler][bundler] to pick up all
+the gems:
+
+```
+$ bundle install
+```
+
+[bundler]: http://gembundler.org
+
+## Usage
+
+The ContextIO classes map pretty much one-to-one to the Context.IO API
+resources, which you can find [on their documentation site][contextiodocs].
+
+[contextiodocs]: http://context.io/docs/2.0
+
+### Authenticate
+
+ContextIO uses two-legged [OAuth][oauth] for authentication, which means you
+need to get an API key from [Context.IO][contextio]. The API key consists of a
+consumer key and a consumer secret, and once you have them you can set up
+ContextIO like this:
+
+```ruby
+ContextIO.configure do |config|
+  config.consumer_key = 'consumer key'
+  config.consumer_secret = 'consumer secret'
+end
+```
+
+[oauth]: http://oauth.net/
+
+### Get an Account object
+
+Once you're authenticated, you can get an `Account` object, which is what you
+will be dealing with most of the time.
+
+```ruby
+account = ContextIO::Account.all.first
+```
+
+You can also find accounts matching a given email address.
+
+```ruby
+account = ContextIO::Account.all(:email => 'me@example.org').first
+```
+
+## Contributing
+
+In the spirit of [free software][free-sw], **everyone** is encouraged to help
+improve this project.
+
+Here are some ways *you* can contribute:
+
+* by using alpha, beta and prerelease versions
+* by reporting bugs
+* by suggesting new features
+* by writing or editing documentation
+* by writing specifications
+* by writing code (**no patch is too small**: fix typos, add comments, clean up
+  inconsistent whitespace)
+* by refactoring code
+* by closing [issues][issues]
+* by reviewing patches
+
+### Submitting an Issue
+
+We use the [GitHub issue tracker][issues] to track bugs and features. Before
+submitting a bug report or feature request, check to make sure it hasn't
+already been submitted. You can indicate support for an existing issue by
+writing a comment saying you have the same issue (please include what version
+of the gem you are using, as well as what version of ruby). When submitting a
+bug report, please include a [gist][gist] that includes a stack trace and any
+details that may be necessary to reproduce the bug, including your gem version,
+Ruby version and operating system. Ideally, a bug report should include a pull
+request with failing specs.
+
+### Submitting a Pull Request
+
+1. Fork the project.
+2. Create a topic branch.
+3. Implement your feature or bug fix.
+4. Add documentation for your feature or bug fix.
+5. Run `bundle exec rake rdoc`. If your changes are not 100% documented, go
+   back to step 4.
+6. Add specs for your feature or bug fix.
+7. Run `bundle exec rake spec`. If your changes are not 100% covered, go back
+   to step 6.
+8. Commit your changes. If necessary, merge in upstream and rebase your
+   changes. Push your changes.
+9. Submit a pull request. Please do not include changes to the gemspec,
+   version or history file.
+
+[free-sw]: http://www.gnu.org/philosophy/free-sw.html
+[issues]: https://github.com/dvyjones/context-io/issues
+
+
+## Copyright
+
+Copyright (c) 2012 Henrik Hodne. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,121 @@
+require 'rubygems'
+require 'rake'
+require 'date'
+
+#############################################################################
+#
+# Helper functions
+#
+#############################################################################
+
+def name
+  @name ||= Dir['*.gemspec'].first.split('.').first
+end
+
+def version
+  line = File.read("lib/#{name}/version.rb")[/^\s*VERSION\s*=\s*.*/]
+  line.match(/.*VERSION\s*=\s*['"](.*)['"]/)[1]
+end
+
+def date
+  Date.today.to_s
+end
+
+def rubyforge_project
+  name
+end
+
+def gemspec_file
+  "#{name}.gemspec"
+end
+
+def gem_file
+  "#{name}-#{version}.gem"
+end
+
+def replace_header(head, header_name)
+  head.sub!(/(\.#{header_name}\s*= ').*'/) { "#{$1}#{send(header_name)}'" }
+end
+
+#############################################################################
+#
+# Standard tasks
+#
+#############################################################################
+
+task :default => :spec
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'yard'
+YARD::Rake::YardocTask.new
+
+#############################################################################
+#
+# Packaging tasks
+#
+#############################################################################
+
+desc "Create tag v#{version} and build and push #{gem_file} to Rubygems"
+task :release => :build do
+  unless `git branch` =~ /^\* master$/
+    puts 'You must be on the master branch to release!'
+    exit!
+  end
+  sh "git commit --allow-empty -a -m 'Release #{version}'"
+  sh "git tag v#{version}"
+  sh 'git push origin master'
+  sh "git push origin v#{version}"
+  sh "gem push pkg/#{gem_file}"
+end
+
+desc "Build #{gem_file} into the pkg directory"
+task :build => :gemspec do
+  sh 'mkdir -p pkg'
+  sh "gem build #{gemspec_file}"
+  sh "mv #{gem_file} pkg"
+end
+
+desc "Generate #{gemspec_file}"
+task :gemspec => :validate do
+  # read spec file and split out manifest section
+  spec = File.read(gemspec_file)
+  head, manifest, tail = spec.split("  # = MANIFEST =\n")
+
+  # replace name, version and date
+  replace_header(head, :name)
+  replace_header(head, :version)
+  replace_header(head, :date)
+  replace_header(head, :rubyforge_project)
+
+  # determine file list from git ls-files
+  files = `git ls-files`.
+    split("\n").
+    sort.
+    reject { |file| file =~ /^\./ }.
+    reject { |file| file =~ /^(rdoc|pkg)/ }.
+    map { |file| "    #{file}" }.
+    join("\n")
+
+  # piece file back together and write
+  manifest = "  s.files = %w(\n#{files}\n  )\n"
+  spec = [head, manifest, tail].join("  # = MANIFEST =\n")
+  File.open(gemspec_file, 'w') { |io| io.write(spec) }
+  puts "Updated #{gemspec_file}"
+end
+
+desc "Validate #{gemspec_file}"
+task :validate do
+  libfiles = Dir['lib/*'] - ["lib/#{name}.rb", "lib/#{name}"]
+  unless libfiles.empty?
+    puts "Directory `lib` should only contain a `#{name}.rb` file and `#{name}` dir."
+    exit!
+  end
+  unless Dir['VERSION*'].empty?
+    puts 'A `VERSION` file at root level violates Gem best practices.'
+    exit!
+  end
+end
+

data/SPEC.md

@@ -0,0 +1,49 @@
+ContextIO spec / roadmap
+========================
+
+These are things that will be included in the "Usage" section of the README
+file. Think of this as a roadmap.
+
+### Getting a list of messages
+
+Once you have an `Account` object, you can get a list of messages as an array
+of `Message` objects.
+
+```ruby
+account.messages
+# => [#<ContextIO::Message to: 'me@example.com', ...>, ...]
+```
+
+You can also search for messages (see the documentation for
+ContextIO::Message#find for the full list of attributes you can search for.
+
+```ruby
+account.messages(:subject => 'Hello, world!').first
+# => #<ContextIO::Message subject: 'Hello, world!', ...>
+```
+
+### The Message object
+
+`Message` objects contains information about that message.
+
+```ruby
+message = account.messages.first
+
+message.subject
+# => "Hello, world!"
+
+message.from
+# => "John Doe <john.doe@example.com>"
+
+message.to
+# => "me@example.com"
+
+message.date
+# => Thu Jan 05 23:30:22 +0100 2012
+
+message.message_id
+# => "abcdef0123456789"
+
+message.email_message_id
+# => "<20120105233022.abcdef0@mta1.mail.example.com>"
+

data/context-io.gemspec

@@ -0,0 +1,96 @@
+Gem::Specification.new do |s|
+  s.specification_version = 2 if s.respond_to? :specification_version=
+  s.required_rubygems_version = Gem::Requirement.new('>= 0') if s.respond_to? :required_rubygems_version=
+  s.rubygems_version = '1.3.5'
+
+  s.name = 'context-io'
+  s.version = '0.0.1'
+  s.date = '2012-01-26'
+  s.rubyforge_project = 'context-io'
+
+  s.summary = 'Ruby wrapper for the context.io API.'
+  s.description = 'Ruby wrapper for the context.io API.'
+
+  s.authors = ['Henrik Hodne']
+  s.email = 'dvyjones@dvyjones.com'
+  s.homepage = 'https://github.com/dvyjones/context-io'
+
+  s.require_paths = %w(lib)
+
+  s.rdoc_options = ['--charset=UTF-8', '--markup tomdoc', '--main README.md']
+  s.extra_rdoc_files = %w(README.md LICENSE)
+
+  s.add_dependency('faraday', '~> 0.7.5')
+  s.add_dependency('simple_oauth', '~> 0.1.5')
+  s.add_dependency('multi_json', '~> 1.0.0')
+  s.add_dependency('webmock', '~> 1.7.10')
+
+  if RUBY_PLATFORM == 'java'
+    s.add_dependency('jruby-openssl', '>= 0')
+  end
+
+  s.add_development_dependency('rspec', '~> 2.8.0')
+  s.add_development_dependency('rake', '~> 0.9.0')
+  s.add_development_dependency('yard', '~> 0.7.4')
+  s.add_development_dependency('yard-rspec', '~> 0.1')
+  s.add_development_dependency('redcarpet', '~> 2.1.0')
+  s.add_development_dependency('github-markup', '~> 0.7.0')
+
+  # = MANIFEST =
+  s.files = %w(
+    Gemfile
+    LICENSE
+    README.md
+    Rakefile
+    SPEC.md
+    context-io.gemspec
+    lib/context-io.rb
+    lib/context-io/account.rb
+    lib/context-io/authentication.rb
+    lib/context-io/config.rb
+    lib/context-io/connection.rb
+    lib/context-io/core_ext/hash.rb
+    lib/context-io/error.rb
+    lib/context-io/error/bad_request.rb
+    lib/context-io/error/client_error.rb
+    lib/context-io/error/forbidden.rb
+    lib/context-io/error/internal_server_error.rb
+    lib/context-io/error/not_found.rb
+    lib/context-io/error/payment_required.rb
+    lib/context-io/error/server_error.rb
+    lib/context-io/error/service_unavailable.rb
+    lib/context-io/error/unauthorized.rb
+    lib/context-io/file.rb
+    lib/context-io/folder.rb
+    lib/context-io/message.rb
+    lib/context-io/oauth_provider.rb
+    lib/context-io/request.rb
+    lib/context-io/request/oauth.rb
+    lib/context-io/resource.rb
+    lib/context-io/response.rb
+    lib/context-io/response/parse_json.rb
+    lib/context-io/response/raise_client_error.rb
+    lib/context-io/response/raise_server_error.rb
+    lib/context-io/source.rb
+    lib/context-io/version.rb
+    spec/account_spec.rb
+    spec/contextio_spec.rb
+    spec/file_spec.rb
+    spec/fixtures/accounts.json
+    spec/fixtures/files.json
+    spec/fixtures/files_group.json
+    spec/fixtures/folders.json
+    spec/fixtures/messages.json
+    spec/fixtures/oauth_providers.json
+    spec/fixtures/sources.json
+    spec/folder_spec.rb
+    spec/message_spec.rb
+    spec/oauth_provider_spec.rb
+    spec/source_spec.rb
+    spec/spec_helper.rb
+  )
+  # = MANIFEST =
+
+  s.test_files = s.files.select { |path| path =~ /^spec\/spec_.*\.rb/ }
+end
+

data/lib/context-io.rb

@@ -0,0 +1,14 @@
+require 'context-io/config'
+require 'context-io/authentication'
+require 'context-io/account'
+require 'context-io/file'
+require 'context-io/oauth_provider'
+require 'context-io/source'
+require 'context-io/message'
+require 'context-io/folder'
+
+# The main ContextIO namespace.
+module ContextIO
+  extend Config
+  extend Authentication
+end

data/lib/context-io/account.rb

@@ -0,0 +1,254 @@
+# encoding: utf-8
+
+require 'context-io/resource'
+
+module ContextIO
+  # An account. Create one of these for every user.
+  #
+  # This does not represent a mail account. An Account can have several mail
+  # accounts attached to it as {Source}s.
+  #
+  # Only the {#first_name} and {#last_name} can be changed after creation.
+  class Account < ContextIO::Resource
+    # @api public
+    # @return [String] The unique ID of the account.
+    attr_reader :id
+
+    # @api public
+    # @return [String] The username of the account.
+    attr_reader :username
+
+    # @api public
+    # @return [Time] When the account was created.
+    attr_reader :created
+
+    # @api public
+    # @return [Time, nil] When the account was suspended, or nil if the account
+    #   isn't suspended.
+    attr_reader :suspended
+
+    # @api public
+    # @return [Array<String>] The email addresses associated with the account.
+    attr_reader :email_addresses
+
+    # @api public
+    # @return [String] The first name of the account holder.
+    attr_accessor :first_name
+
+    # @api public
+    # @return [String] The last name of the account holder.
+    attr_accessor :last_name
+
+    # @api public
+    # @return [Time, nil] When the account password expired, or nil if the
+    #   password hasn't expired.
+    attr_reader :password_expired
+
+    # @api public
+    # @return [Array<Source>] The sources associated with this account.
+    attr_reader :sources
+
+    # Get all the accounts, optionally filtered with a query
+    #
+    # @api public
+    #
+    # @param [Hash] query The query to filter accounts by. All fields are
+    #   optional.
+    # @option query [String] :email Only return accounts associated with this
+    #   email address.
+    # @option query [:invalid_credentials, :connection_impossible,
+    #   :no_access_to_all_mail, :ok, :temp_disabled, :disabled] :status Only
+    #   return accounts with sources whose status is the one given. If an
+    #   account has several sources, only those matching the given status will
+    #   be included in the response.
+    # @option query [true, false] :status_ok Whether to only return accounts
+    #   with sources that are working or not working properly (true/false,
+    #   respectively). As with the `:status` filter above, only sources matching
+    #   the specific value are included in the response.
+    # @option query [Integer] :limit The maximum number of results to return.
+    # @option query [Integer] :offset The offset to start the list at (0 is no
+    #   offset).
+    #
+    # @example Fetch all accounts
+    #   ContextIO::Account.all
+    #
+    # @example Fetch all accounts with the email address me@example.com
+    #   ContextIO::Account.all(:email => 'me@example.com')
+    #
+    # @return [Array<Account>] The accounts matching the query, or all if no
+    #   query is given.
+    def self.all(query={})
+      query[:status] = query[:status].to_s.upcase if query[:status]
+      if query.has_key?(:status_ok)
+        query[:status_ok] = query[:status_ok] ? '1' : '0'
+      end
+      get('/2.0/accounts', query).map do |account|
+        Account.from_json(account)
+      end
+    end
+
+    # Find an account given its ID
+    #
+    # @api public
+    #
+    # @param [String] id The ID of the account to look up.
+    #
+    # @example Find the account with the ID 'foobar'
+    #   ContextIO::Account.find('foobar')
+    #
+    # @return [Account] The account with the given ID.
+    def self.find(id)
+      Account.from_json(get("/2.0/accounts/#{id}"))
+    end
+
+    # Initialize an Account
+    #
+    # @api public
+    #
+    # @param [Hash] attributes The attributes to set on the account (all values
+    #   are optional).
+    # @option attributes [String] :email The primary email address of the
+    #   account holder.
+    # @option attributes [String] :first_name The first name of the account
+    #   holder.
+    # @option attributes [String] :last_name The last name of the account
+    #   holder.
+    #
+    # @example Initialize an account with the email 'me@example.com'
+    #   ContextIO::Account.new(:email => 'me@example.com')
+    def initialize(attributes={})
+      @email_addresses = [attributes[:email]] if attributes[:email]
+      @first_name = attributes[:first_name]
+      @last_name = attributes[:last_name]
+    end
+
+    # Send the account info to Context.IO
+    #
+    # If this is the first time the account is sent to Context.IO, the first
+    # email address set will be sent as the primary email address, and the first
+    # and last name will be sent if they are specified. You are required to
+    # specify one email address.
+    #
+    # If the account has been sent to Context.IO before, this will update the
+    # first and last name.
+    #
+    # @api public
+    #
+    # @raise [ArgumentError] If there isn't at least one email address specified
+    #   in the {#email_addresses} field.
+    #
+    # @example Create an account
+    #   account = ContextIO::Account.new(:email => 'me@example.com')
+    #   account.save
+    #
+    # @return [true, false] Whether the save succeeded or not.
+    def save
+      self.id ? update_record : create_record
+    end
+
+    # Update attributes on the account object and then send them to Context.IO
+    #
+    # @api public
+    #
+    # @param [Hash] attributes The attributes to update.
+    # @option attributes [String] :first_name The first name of the account
+    #   holder.
+    # @option attributes [String] :last_name The last name of the account
+    #   holder.
+    #
+    # @example Update the account holder's name to "John Doe"
+    #   account.update_attributes(:first_name => 'John', :last_name => 'Doe')
+    #
+    # @return [true, false] Whether the update succeeded or not.
+    def update_attributes(attributes)
+      @first_name = attributes[:first_name] if attributes[:first_name]
+      @last_name = attributes[:last_name] if attributes[:last_name]
+
+      response = put("/2.0/accounts/#{self.id}", attributes)
+
+      response['success']
+    end
+
+    # Create the account on Context.IO
+    #
+    # @api private
+    #
+    # This will only send the first email address in the email_addresses
+    # attribute (which is required) as well as the first and last name if they
+    # are not-falsey.
+    #
+    # @return [true, false] Whether the creation succeeded or not.
+    def create_record
+      unless self.email_addresses && self.email_addresses.first
+        raise ArgumentError.new('You must specify an email address')
+      end
+
+      attributes = { :email => self.email_addresses.first }
+      attributes[:first_name] = self.first_name if self.first_name
+      attributes[:last_name] = self.last_name if self.last_name
+
+      response = post('/2.0/accounts', attributes)
+      @id = response['id']
+
+      @saved = response['success']
+    end
+    private :create_record
+
+    # Update the account on Context.IO
+    #
+    # Only sends the first and last name, as they are the only attributes the
+    # Context.IO API allows you to update.
+    #
+    # @api private
+    #
+    # @return [true, false] Whether the update succeeded or not.
+    def update_record
+      attributes = {}
+      attributes[:first_name] = self.first_name if self.first_name
+      attributes[:last_name] = self.last_name if self.last_name
+      response = put("/2.0/accounts/#{self.id}", attributes)
+
+      response['success']
+    end
+    private :update_record
+
+    # Create an Account instance from the JSON returned by the Context.IO server
+    #
+    # @api private
+    #
+    # @param [Hash] json The parsed JSON object returned by a Context.IO API
+    #   request. See their documentation for what keys are possible.
+    #
+    # @return [Account] An account with the given attributes.
+    def self.from_json(json)
+      account = new
+      account.instance_eval do
+        @id = json['id']
+        @username = json['username']
+        if json['created'] == 0
+          @created = nil
+        else
+          @created = Time.at(json['created'])
+        end
+        if json['suspended'] == 0
+          @suspended = nil
+        else
+          @suspended = Time.at(json['suspended'])
+        end
+        @email_addresses = json['email_addresses']
+        @first_name = json['first_name']
+        @last_name = json['last_name']
+        if json['password_expired'] == 0
+          @password_expired = nil
+        else
+          @password_expired = json['password_expired']
+        end
+        @sources = json['sources'].map do |source|
+          Source.from_json(@id, source)
+        end
+      end
+
+      account
+    end
+  end
+end