contextio-lite 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9a4c95db7436871ec9123eb36072dd02e24f5078
+  data.tar.gz: 55b65431a9f3f5b517992e5ed3cde2ac2aa4198a
+SHA512:
+  metadata.gz: 56066f305c8e1341b3f911f18a25bce82297c99c1b6697569704d954fae1503f9c57179e16a8cc54917d4924b6c0d1b2e133da7738b1786e71fd137989d42641
+  data.tar.gz: 4d245707e67caeac959882263e47dd5b121f7464bf01251b707259e4b463d8c2992bc402f6c776af395da4d1d6a690b17c14256a6910464ed6c6853e495b86ab

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in contextio-lite.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 javi
+
+MIT License
+
+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,114 @@
+# Contextio::Lite
+
+This is API client for the [Context.IO Lite](https://context.io/) version based on [Context.IO Ruby](https://github.com/contextio/contextio-ruby) for the 2.0 version.
+It works in the same way as the official, calling first a user object and then working with the collections...
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'contextio-lite'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install contextio-lite
+
+## Usage
+
+### Get a client
+
+```ruby
+require 'contextio/lite'
+
+client = ContextIO::Lite.new(API_KEY, API_SECRET)
+```
+
+### Dealing with users
+
+List all the registered lite users IDs
+
+```ruby
+p client.users.map(&:id)
+```
+
+CRUD
+
+```ruby
+user = client.users.create email: 'bob@gmail.com', first_name: 'Bob', server: 'imap.gmail.com' username: 'bob', 'use_sll':true, 'port': 993, 'type': 'IMAP
+
+user_id = user.id
+
+client.users[user_id].update :hash_attrs
+
+client.users[user_id].delete
+```
+
+### Retrieving messages
+
+To access the emails, first you need to select an email_account and the folder containing your email
+
+So if you want to list the user email accounts or folders you can do like this
+
+```ruby
+p client[user_id].email_accounts.map(&:label)
+p client[user_id].email_accounts[label].folders.map(&:name) # can access email_accounts by number => email_accounts[0]
+```
+
+Listing all the email subjects inside a folder (limited by context IO to 100)
+```ruby
+client[user_id].email_accounts[0].folders['INBOX'].messages do
+    p messages.subject
+end
+```
+
+And if you want to filter the emails
+
+```ruby
+client[user_id].email_accounts[0].folder['INBOX'].messages.where(limit: 3)
+```
+
+You also may want to access the content of one message
+
+```ruby
+client[user_id].email_accounts[0].folder['INBOX'].messages['<message_id>'].body_plain # or body_html
+
+client[user_id].email_accounts[0].folder['INBOX'].messages['<message_id>'].with(include_body:true).body_plain
+```
+
+The first one calls https://api.context.io/lite/users/id/email_accounts/label/folders/folder/messages/message_id/body
+and the second calls https://api.context.io/lite/users/id/email_accounts/label/folders/folder/messages/message_id?include_body=1
+but they return the same.
+
+And the above should works also with 'flags' or 'headers'.
+
+### Webhooks
+
+One of the main feature that this version has and 2.0 doesn't is the real-time webhooks.
+So in order to work with them we can do
+
+```ruby
+client[user_id].webhooks.map(&:webhook_id) # listing all the webhooks an user has
+
+client[user_id].create callback_url, failure_url, filter_folder_added: 'INBOX', include_body: true
+```
+
+So it will call the callback_url every time there is a new message on the user INBOX folder, posting the message info and body included.
+
+
+## Contributing
+
+1. Fork it ( https://github.com/javijuol/contextio-lite/fork )
+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
+
+## Copyright
+
+This gem is distributed under the MIT License. See LICENSE.md for details.

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/contextio-lite.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require File.expand_path('../lib/contextio', __FILE__)
+
+Gem::Specification.new do |spec|
+  spec.name          = 'contextio-lite'
+  spec.version       = ContextIO.version
+  spec.authors       = ['Javier Juan']
+  spec.email         = ['javier@promivia.com']
+  spec.summary       = %q{Provides interface to Context.IO Lite API}
+  spec.description   = %q{Short implementation of a client rest API for the Context.IO Lite API}
+  spec.homepage      = 'https://github.com/javijuol/contextio-lite'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.7'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'debase', '~> 0'
+  spec.add_development_dependency 'faraday', '~> 0.9.1'
+  spec.add_development_dependency 'faraday_middleware', '~> 0.9.1'
+
+end

data/lib/contextio.rb

@@ -0,0 +1,14 @@
+module ContextIO
+	VERSION = '0.0.2'
+
+	# @private
+	# Handle for the `API` instance. For internal use only.
+	attr_reader :api
+
+	def self.version
+		VERSION
+	end
+
+end
+
+require_relative 'contextio/lite'

data/lib/contextio/api/abstract_api.rb

@@ -0,0 +1,213 @@
+require 'uri'
+require 'json'
+require 'faraday'
+require 'faraday_middleware'
+
+module ContextIO
+	module API
+		class AbstractAPI
+
+			# @private
+			BASE_URL = 'https://api.context.io'
+
+			# @return [String] The version of the Context.IO API this version of the
+			#   gem is intended for use with.
+			def self.version
+				raise NotDefinedError, 'VERSION is not defined in your API subclassed model.' if self::VERSION.nil?
+				self::VERSION
+			end
+
+			# @return [String] The base URL the API is served from.
+			def self.base_url
+				BASE_URL
+			end
+
+			def self.user_agent_string
+				raise NotDefinedError, 'user_agent_string undefined in your API subclassed model.'
+			end
+
+			def user_agent_string
+				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
+			#   @return [String] The OAuth secret for the user's Context.IO account.
+			# @!attribute [r] opts
+			#   @return [Hash] opts Optional options for OAuth connections.
+			attr_reader :key, :secret, :opts
+
+			# @param [String] key The user's OAuth key for their Context.IO account.
+			# @param [String] secret The user's OAuth secret for their Context.IO account.
+			# @param [Hash] opts Optional options for OAuth connections. ie. :timeout and :open_timeout are supported
+			def initialize(key, secret, opts={})
+				@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.
+			#
+			# @param [String] resource_path The resource_path or full resource URL for
+			#   the resource being acted on.
+			# @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 = {})
+				"/#{version}/#{strip_resource_path(resource_path)}#{self.class.hash_to_url_params(params)}"
+			end
+
+			# Makes a request against the Context.IO API.
+			#
+			# @param [String, Symbol] method The HTTP verb for the request (lower case).
+			# @param [String] resource_path The path to the resource in question.
+			# @param [{String, Symbol => String, Symbol, Array<String, Symbol>}] params
+			#   A Hash of the query parameters for the action represented by this
+			#   request.
+			#
+			# @raise [API::Error] if the response code isn't in the 200 or 300 range.
+			def request(method, resource_path, params = {})
+				response = oauth_request(method, resource_path, params, { 'Accept' => 'application/json' })
+
+				with_error_handling(response) do |response|
+					parse_json(response.body)
+				end
+			end
+
+			def raw_request(method, resource_path, params={})
+				response = oauth_request(method, resource_path, params)
+
+				with_error_handling(response) do |response|
+					response.body
+				end
+			end
+
+			protected
+
+			# Makes a request signed for OAuth, encoding parameters correctly, etc.
+			#
+			# @param [String, Symbol] method The HTTP verb for the request (lower case).
+			# @param [String] resource_path The path to the resource in question.
+			# @param [{String, Symbol => String, Symbol, Array<String, Symbol>}] params
+			#   A Hash of the query parameters for the action represented by this
+			#   request.
+			# @param [{String, Symbol => String, Symbol, Array<String, Symbol>}] headers
+			#   A Hash of headers to be merged with the default headers for making
+			#   requests.
+			#
+			# @return [Faraday::Response] The response object from the request.
+			def oauth_request(method, resource_path, params, headers=nil)
+				normalized_params = params.inject({}) do |normalized_params, (key, value)|
+					normalized_params[key.to_sym] = value
+					normalized_params
+				end
+
+				connection.send(method, path(resource_path), normalized_params, headers) do |request|
+					if request.method == :put
+						request.params = normalized_params
+						request.body   = {}
+					end
+				end
+			end
+
+			# So that we can accept full URLs, this strips the domain and version number
+			# out and returns just the resource path.
+			#
+			# @param [#to_s] resource_path The full URL or path for a resource.
+			#
+			# @return [String] The resource path.
+			def strip_resource_path(resource_path)
+				resource_path.to_s.gsub("#{base_url}/#{version}/", '')
+			end
+
+			# Context.IO's API expects query parameters that are arrays to be comma
+			# separated, rather than submitted more than once. This munges those arrays
+			# and then URL-encodes the whole thing into a query string.
+			#
+			# @param [{String, Symbol => String, Symbol, Array<String, Symbol>}] params
+			#   A Hash of the query parameters.
+			#
+			# @return [String] A URL-encoded version of the query parameters.
+			def self.hash_to_url_params(params = {})
+				return '' if params.empty?
+
+				params = params.inject({}) do |memo, (k, v)|
+					memo[k] = Array(v).join(',')
+
+					memo
+				end
+
+				"?#{URI.encode_www_form(params)}"
+			end
+
+			# @!attribute [r] connection
+			# @return [Faraday::Connection] A handle on the Faraday connection object.
+			def connection
+				@connection ||= Faraday::Connection.new(base_url) do |faraday|
+					faraday.headers['User-Agent'] = user_agent_string
+
+					faraday.request :oauth, consumer_key: key, consumer_secret: secret
+					faraday.request :url_encoded
+
+					faraday.adapter Faraday.default_adapter
+				end
+			end
+
+			# Errors can come in a few shapes and we want to detect them and extract the
+			# useful information. If no errors are found, it calls the provided block
+			# and passes the response through.
+			#
+			# @param [Faraday::Response] response A response object from making a request to the
+			#   API with Faraday.
+			#
+			# @raise [API::Error] if the response code isn't in the 200 or 300 range.
+			def with_error_handling(response, &block)
+				return block.call(response) if response.success?
+
+				parsed_body = parse_json(response.body)
+				message = determine_best_error_message(parsed_body) || "HTTP #{response.status} Error"
+
+				raise ContextIO::API::Error, message
+			end
+
+			# Parses JSON if there's valid JSON passed in.
+			#
+			# @param [String] document A string you suspect may be a JSON document.
+			#
+			# @return [Hash, Array, Nil] Either a parsed version of the JSON document or
+			#   nil, if the document wasn't valid JSON.
+			def parse_json(document)
+				return JSON.parse(document.to_s)
+			rescue JSON::ParserError => e
+				return nil
+			end
+
+
+			# Given a parsed JSON body from an error response, figures out if it can
+			# pull useful information therefrom.
+			#
+			# @param [Hash] parsed_body A Hash parsed from a JSON document that may
+			#   describe an error condition.
+			#
+			# @return [String, Nil] If it can, it will return a human-readable
+			#   error-describing String. Otherwise, nil.
+			def determine_best_error_message(parsed_body)
+				return unless parsed_body.respond_to?(:[])
+
+				if parsed_body['type'] == 'error'
+					return parsed_body['value']
+				elsif parsed_body.has_key?('success') && !parsed_body['success']
+					return [parsed_body['feedback_code'], parsed_body['connectionLog']].compact.join("\n")
+				end
+			end
+		end
+
+		class NotDefinedError < StandardError; end
+		class Error < StandardError; end
+
+	end
+end

data/lib/contextio/api/association_helpers.rb

@@ -0,0 +1,17 @@
+module ContextIO
+  module API
+    module AssociationHelpers
+      def self.class_for_association_name(association_name)
+        associations[association_name]
+      end
+
+      def self.register_resource(klass, association_name)
+        associations[association_name] = klass
+      end
+
+      def self.associations
+        @associations ||= {}
+      end
+    end
+  end
+end