context-io 0.0.1

data/lib/context-io/authentication.rb

@@ -0,0 +1,23 @@
+# encoding: utf-8
+
+module ContextIO
+  # Methods related to authentication and configuration.
+  #
+  # @api private
+  module Authentication
+    # @return [Hash] The authentication details for OAuth.
+    def authentication
+      {
+        :consumer_key => consumer_key,
+        :consumer_secret => consumer_secret,
+        :token => nil,
+        :token_secret => nil,
+      }
+    end
+
+    # @return [Boolean] Whether authentication details are configured or not.
+    def authenticated?
+      authentication[:consumer_key] and authentication[:consumer_secret]
+    end
+  end
+end

data/lib/context-io/config.rb

@@ -0,0 +1,103 @@
+require 'context-io/version'
+
+module ContextIO
+  # Defines constants and methods related to configuration
+  #
+  # You shouldn't interact with this module directly, as it's included in the
+  # {ContextIO} module. Mostly you'll use the {#configure} method on
+  # {ContextIO}, see the example on {#configure}.
+  #
+  # @see #configure
+  module Config
+    # The HTTP connection adapter that will be used to connect if none is set
+    DEFAULT_ADAPTER = :net_http
+
+    # The Faraday connection options if none is set
+    DEFAULT_CONNECTION_OPTIONS = {}
+
+    # The consumer key if none is set
+    DEFAULT_CONSUMER_KEY = nil
+
+    # The consumer secret if none is set
+    DEFAULT_CONSUMER_SECRET = nil
+
+    # The proxy server if none is set
+    DEFAULT_PROXY = nil
+
+    # The value of sent in the 'User-Agent' header if none is set
+    DEFAULT_USER_AGENT = "context-io ruby gem #{ContextIO::VERSION}"
+
+    # The configuration options that are settable.
+    VALID_OPTIONS_KEYS = [
+      :adapter,
+      :connection_options,
+      :consumer_key,
+      :consumer_secret,
+      :proxy,
+      :user_agent
+    ]
+
+    # @return [Symbol] The HTTP connection adapter. Check the Faraday
+    #   documentation for possible adapters.
+    attr_accessor :adapter
+
+    # @return [Hash] Connection options passed to the Faraday connection object.
+    attr_accessor :connection_options
+
+    # @return [String] The OAuth consumer key received from Context.IO.
+    attr_accessor :consumer_key
+
+    # @return [String] The OAuth consumer secret received from Context.IO.
+    attr_accessor :consumer_secret
+
+    # @return [String, URI] The URI to the HTTP proxy to use.
+    attr_accessor :proxy
+
+    # @return [String] The value to be sent in the User-Agent header. Probably
+    #   doesn't need to be changed unless you're writing a big app, or another
+    #   library based on this one.
+    attr_accessor :user_agent
+
+    # Makes sure the default values are always set
+    #
+    # @api private
+    def self.extended(base)
+      base.reset
+    end
+
+    # Configure with a block
+    #
+    # @api public
+    #
+    # @example Configuring OAuth
+    #   ContextIO.configure do |config|
+    #     config.consumer_key = 'my_consumer_key'
+    #     config.consumer_secret = 'my_consumer_secret'
+    #   end
+    #
+    # @return [self]
+    def configure
+      yield self
+      self
+    end
+
+    # Reset the configuration to the default values
+    #
+    # @api public
+    #
+    # @example Reset the configuration
+    #   ContextIO.adapter = :some_erroneous_thing
+    #   ContextIO.reset
+    #   ContextIO.adapter # => DEFAULT_ADAPTER
+    #
+    # @return [void]
+    def reset
+      self.adapter            = DEFAULT_ADAPTER
+      self.connection_options = DEFAULT_CONNECTION_OPTIONS
+      self.consumer_key       = DEFAULT_CONSUMER_KEY
+      self.consumer_secret    = DEFAULT_CONSUMER_SECRET
+      self.proxy              = DEFAULT_PROXY
+      self.user_agent         = DEFAULT_USER_AGENT
+    end
+  end
+end

data/lib/context-io/connection.rb

@@ -0,0 +1,45 @@
+require 'faraday'
+require 'context-io/core_ext/hash'
+require 'context-io/request/oauth'
+require 'context-io/response/parse_json'
+require 'context-io/response/raise_client_error'
+require 'context-io/response/raise_server_error'
+
+module ContextIO
+  # Methods for creating a connection to the API server.
+  #
+  # @api private
+  # @private
+  module Connection
+    # Create and configure a Faraday connection
+    #
+    # @api private
+    #
+    # @param [true, false] raw Set this to true to disable JSON parsing of the
+    #   response body.
+    #
+    # @return [Faraday::Connection] A Connection object that's correctly
+    #   configured.
+    def connection(raw=false)
+      default_options = {
+        :headers => {
+          :accept => 'application/json',
+          :user_agent => ContextIO.user_agent,
+        },
+        :proxy => ContextIO.proxy,
+        :ssl => { :verify => false },
+        :url => 'https://api.context.io'
+      }
+      Faraday.new(default_options.deep_merge(ContextIO.connection_options)) do |builder|
+        builder.use ContextIO::Request::ContextIOOAuth, ContextIO.authentication if ContextIO.authenticated?
+        builder.use Faraday::Request::UrlEncoded
+        builder.use ContextIO::Response::RaiseClientError
+        builder.use ContextIO::Response::ParseJson unless raw
+        builder.use ContextIO::Response::RaiseServerError
+        builder.adapter(ContextIO.adapter)
+      end
+    end
+    private :connection
+  end
+end
+

data/lib/context-io/core_ext/hash.rb

@@ -0,0 +1,31 @@
+# Hash extensions
+#
+# This is borrowed from ActiveSupport. We don't want the entire ActiveSupport
+# library (it's huge), so we'll just add this method.
+class Hash
+  # Merge self with another hash recursively
+  #
+  # @api public
+  #
+  # @param [Hash] hash The hash to merge into this one.
+  #
+  # @example Merge two hashes with some common keys
+  #   a_hash = { :foo => :bar, :baz => { :foobar => "hey" }}
+  #   another_hash = { :foo => :foobar, :baz => { :foo => :bar }}
+  #   a_hash.deep_merge(another_hash)
+  #   # => { :foo => :foobar, :baz => { :foobar => "hey", :foo => :bar }}
+  #
+  # @return [Hash] The given hash merged recursively into this one.
+  def deep_merge(hash)
+    target = self.dup
+    hash.keys.each do |key|
+      if hash[key].is_a?(Hash) && self[key].is_a?(Hash)
+        target[key] = target[key].deep_merge(hash[key])
+        next
+      end
+      target[key] = hash[key]
+    end
+    target
+  end
+end
+

data/lib/context-io/error.rb

@@ -0,0 +1,24 @@
+# encoding: utf-8
+
+module ContextIO
+  # Base class for ContextIO exceptions.
+  #
+  # @api public
+  class Error < StandardError
+    # @return [Hash{String => String}] The HTTP headers of the response.
+    attr_reader :http_headers
+
+    # Initialize a new ContextIO error
+    #
+    # @api private
+    # @private
+    #
+    # @param [String] message The error message.
+    # @param [Hash{String => String}] http_headers The HTTP headers.
+    def initialize(message, http_headers)
+      @http_headers = Hash[http_headers]
+      super(message)
+    end
+  end
+end
+

data/lib/context-io/error/bad_request.rb

@@ -0,0 +1,12 @@
+require 'context-io/error/client_error'
+
+module ContextIO
+  # Raised when Context.IO returns the HTTP status code 400
+  #
+  # This usually means that some required info is missing.
+  #
+  # @api public
+  class Error::BadRequest < ContextIO::Error::ClientError
+  end
+end
+

data/lib/context-io/error/client_error.rb

@@ -0,0 +1,10 @@
+require 'context-io/error'
+
+module ContextIO
+  # Raised when Context.IO returns a 4xx HTTP status code
+  #
+  # @api public
+  class Error::ClientError < ContextIO::Error
+  end
+end
+

data/lib/context-io/error/forbidden.rb

@@ -0,0 +1,12 @@
+require 'context-io/error/client_error'
+
+module ContextIO
+  # Raised when ContextIO returns the HTTP status code 403
+  #
+  # This usually means that the resource isn't accessible.
+  #
+  # @api public
+  class Error::Forbidden < ContextIO::Error::ClientError
+  end
+end
+

data/lib/context-io/error/internal_server_error.rb

@@ -0,0 +1,10 @@
+require 'context-io/error/server_error'
+
+module ContextIO
+  # Raised when Context.IO returns the HTTP status code 500.
+  #
+  # @api public
+  class Error::InternalServerError < ContextIO::Error::ServerError
+  end
+end
+

data/lib/context-io/error/not_found.rb

@@ -0,0 +1,12 @@
+require 'context-io/error/client_error'
+
+module ContextIO
+  # Raised when Context.IO returns the HTTP status code 404
+  #
+  # This means that the resource you tried to get doesn't exist.
+  #
+  # @api public
+  class Error::NotFound < ContextIO::Error::ClientError
+  end
+end
+

data/lib/context-io/error/payment_required.rb

@@ -0,0 +1,13 @@
+require 'context-io/error/client_error'
+
+module ContextIO
+  # Raised when Context.IO returns the HTTP status code 402
+  #
+  # This means that you're trying to do something that your plan isn't allowed
+  # to do (anymore), so you need to log in and upgrade your plan.
+  #
+  # @api public
+  class Error::PaymentRequired < ContextIO::Error::ClientError
+  end
+end
+

data/lib/context-io/error/server_error.rb

@@ -0,0 +1,10 @@
+require 'context-io/error'
+
+module ContextIO
+  # Raised when Context.IO returns a 5xx HTTP status code.
+  #
+  # @api public
+  class Error::ServerError < ContextIO::Error
+  end
+end
+

data/lib/context-io/error/service_unavailable.rb

@@ -0,0 +1,13 @@
+require 'context-io/error/server_error'
+
+module ContextIO
+  # Raised when Context.IO returns the HTTP status code 503
+  #
+  # The 503 status code means a request required a connection to the mail
+  # server, but that connection failed.
+  #
+  # @api public
+  class Error::ServiceUnavailable < ContextIO::Error::ServerError
+  end
+end
+

data/lib/context-io/error/unauthorized.rb

@@ -0,0 +1,12 @@
+require 'context-io/error/client_error'
+
+module ContextIO
+  # Raised when Context.IO returns the HTTP status code 401
+  #
+  # This means that the OAuth signature can't be validated.
+  #
+  # @api public
+  class Error::Unauthorized < ContextIO::Error::ClientError
+  end
+end
+

data/lib/context-io/file.rb

@@ -0,0 +1,234 @@
+require 'context-io/resource'
+
+module ContextIO
+  # A file found as an email attachment
+  #
+  # @api public
+  class File < Resource
+    # @api public
+    # @return [String] The ID of the file
+    attr_reader :id
+
+    # @api public
+    # @return [Integer] The size of the file, in bytes.
+    attr_reader :size
+
+    # @api public
+    # @return [String] The MIME type of the file.
+    attr_reader :type
+
+    # @api public
+    # @return [String] The subject of the message this file was attached to
+    attr_reader :subject
+
+    # @api public
+    # @return [Time] When this file was sent
+    attr_reader :date
+
+    # @api public
+    # @return [Hash] Information on the different addresses attached to this
+    #   file's message.
+    attr_reader :addresses
+
+    # @api public
+    # @return [String] The full filename
+    attr_reader :file_name
+
+    # @api public
+    # @return [Integer]
+    attr_reader :body_section
+
+    # @api public
+    # @return [true, false] Whether the file supports preview
+    attr_reader :supports_preview
+
+    # @api public
+    # @return [String] The (Context.IO) ID of the message this file was attached to
+    attr_reader :message_id
+
+    # @api public
+    # @return [Time] When Context.IO indexed the file (not the same as when it
+    #   was sent)
+    attr_reader :date_indexed
+
+    # @api public
+    # @return [String] The email message ID (The Message-ID header)
+    attr_reader :email_message_id
+
+    # @api public
+    # @return [Hash] Information about the people involved with the message
+    attr_reader :person_info
+
+    # @api public
+    # @return [Array] The file name split up into parts
+    attr_reader :file_name_structure
+
+    # Get all files for a given account, optionally filtered with a query
+    #
+    # @see Account#messages
+    #
+    # @api public
+    #
+    # @param [Account, #to_s] account The account or account ID to search for
+    #   files in.
+    # @param [Hash] query A query to filter files by.
+    # @option query [String, Regexp] :file_name The filename to search for. The
+    #   string can contain shell globs ('*', '?' and '[]').
+    # @option query [String] :email The email address of the contact for whom
+    #   you want the latest files exchanged with. By "exchanged with contact X",
+    #   we mean any email received from contact X, sent to contact X or sent by
+    #   anyone to both contact X and the source owner.
+    # @option query [String] :to The email address of a contact files have been
+    #   sent to.
+    # @option query [String] :from The email address of a contact files have
+    #   been sent from.
+    # @option query [String] :cc The email address of a contact CC'ed on the
+    #   messages.
+    # @option query [String] :bcc The email address of a contact BCC'ed on the
+    #   messages.
+    # @option query [#to_i] :date_before Only include files attached to messages
+    #   sent before this timestamp. The value of this filter is applied to the
+    #   Date header of the message, which refers to the time the message is sent
+    #   from the origin.
+    # @option query [#to_i] :date_after Only include files attached to messages
+    #   sent after this timestamp. The value of this filter is applied to the
+    #   Date header of the message, which refers to the time the message is sent
+    #   from the origin.
+    # @option query [#to_i] :indexed_before Only include files attached to
+    #   messages indexed before this timestamp. This is not the same as the date
+    #   of the email, it is the time Context.IO indexed this message.
+    # @option query [#to_i] :indexed_after Only include files attached to
+    #   messages indexed after this timestamp. This is not the same as the date
+    #   of the email, it is the time Context.IO indexed this message.
+    # @option query [true, false] :group_by_revisions (false) If this is set to
+    #   true, the method will return an array of Hashes, where each Hash
+    #   represents a group of revisions of the same file. The Hash has an
+    #   `:occurences` field, which is an Array of {File} objects, a `:file_name`
+    #   field, which is the name of the file, and a `:latest_date` field, which
+    #   is a Time object representing the last time a message with this file was
+    #   sent.
+    # @option query [#to_i] :limit The maximum count of results to return.
+    # @option query [#to_i] :offset (0) The offset to begin returning files at.
+    #
+    # @example Get all files for the account
+    #   files = ContextIO::File.all(account)
+    #
+    # @example Get 10 files that we have sent
+    #   files = ContextIO::File.all(account,
+    #     :from => account.email_addresses.first,
+    #     :limit => 10
+    #   )
+    #
+    # @example Find PDF files
+    #   files = ContextIO::File.all(account, :file_name => '*.pdf')
+    #
+    # @example Find JP(E)G files
+    #   files = ContextIO::File.all(account, :file_name => /\.jpe?g$/)
+    #
+    # @return [Array<File>, Array<Hash>] The matching file objects. If the
+    #   `:group_by_revisions` flag is set, the return value changes, see the
+    #   documentation for that flag above.
+    def self.all(account, query={})
+      if query[:file_name] && query[:file_name].is_a?(Regexp)
+        query[:file_name] = "/#{query[:file_name].source}/"
+      end
+
+      [:date_before, :date_after, :indexed, :indexed_after].each do |field|
+        if query[field] && query[field].respond_to?(:to_i)
+          query[field] = query[field].to_i
+        end
+      end
+
+      if query[:group_by_revisions]
+        query[:group_by_revisions] = query[:group_by_revisions] ? '1' : '0'
+      end
+
+      account_id = account.is_a?(Account) ? account.id : account.to_s
+      get("/2.0/accounts/#{account_id}/files", query).map do |file|
+        if query[:group_by_revisions]
+          occurences = file['occurences'].map do |file|
+            File.from_json(account_id, file)
+          end
+
+          {
+            :occurences => occurences,
+            :file_name => file['file_name'],
+            :latest_date => Time.at(file['latest_date'].to_i)
+          }
+        else
+          File.from_json(account_id, file)
+        end
+      end
+    end
+
+    # Fetch the content of the message.
+    #
+    # @api public
+    #
+    # @note Data transfer for this call is metered and charged at the end of the
+    #   month. See [Context.IO's pricing page](http://context.io/pricing) for
+    #   more info.
+    #
+    # @return [String] The raw contents of the file.
+    def content
+      get("/2.0/accounts/#@account_id/files/#@id/content", :raw => true)
+    end
+
+    # Create a File with the JSON from Context.IO.
+    #
+    # @api private
+    #
+    # @param [String] account_id The account ID.
+    # @param [Hash] json The parsed JSON object returned by a Context.IO API
+    #   request. See their documentation for possible keys.
+    #
+    # @return [File] A file with the given attributes.
+    def self.from_json(account_id, json)
+      file = new
+      file.instance_eval do
+        @id = json['file_id']
+        @account_id = account_id
+        @size = json['size']
+        @type = json['type']
+        @subject = json['subject']
+        @date = Time.at(json['date'])
+        @addresses = {}
+        json['addresses'].each do |type, info|
+          @addresses[type.to_sym] = {}
+          if info.is_a?(Hash)
+            info.each do |key, value|
+              @addresses[type.to_sym][key.to_sym] = value
+            end
+          elsif info.is_a?(Array)
+            @addresses[type.to_sym] = []
+            info.each do |email_info|
+              @addresses[type.to_sym] << {}
+              email_info.each do |key, value|
+                @addresses[type.to_sym].last[key.to_sym] = value
+              end
+            end
+          end
+        end
+        @file_name = json['file_name']
+        @body_section = json['body_section']
+        @supports_preview = json['supports_preview']
+        @message_id = json['message_id']
+        @date_indexed = Time.at(json['date_indexed'])
+        @email_message_id = json['email_message_id']
+        @person_info = {}
+        json['person_info'].each do |email, info|
+          @person_info[email] = {}
+          info.each do |key, value|
+            @person_info[email][key.to_sym] = value
+          end
+        end
+        @file_name_structure = []
+        json['file_name_structure'].each do |part|
+          @file_name_structure << [part.first, part.last.to_sym]
+        end
+      end
+
+      file
+    end
+  end
+end