contextio 0.5.0 → 1.0.0

data/lib/contextio/account.rb

@@ -0,0 +1,132 @@
+require 'contextio/api/resource'
+require 'contextio/api/association_helpers'
+require 'contextio/account_sync_data'
+
+class ContextIO
+  class Account
+    include ContextIO::API::Resource
+
+    self.primary_key = :id
+    self.association_name = :account
+
+    has_many :sources
+    has_many :connect_tokens
+    has_many :messages
+    has_many :threads
+    has_many :webhooks
+    has_many :contacts
+    has_many :files
+
+    # @!attribute [r] id
+    #   @return [String] The id assigned to this account by Context.IO.
+    # @!attribute [r] username
+    #   @return [String] The username assigned to this account by Context.IO.
+    # @!attribute [r] first_name
+    #   @return [String] The account holder's first name.
+    # @!attribute [r] last_name
+    #   @return [String] The account holder's last name.
+    lazy_attributes :id, :username, :created, :suspended, :first_name,
+                    :last_name, :password_expired, :nb_messages, :nb_files
+    private :created, :suspended, :password_expired
+
+    def email_addresses
+      # It would be nice if the data returned from the API were formatted like
+      # other resources, but it isn't. So hacks.
+      @email_addresses = nil if @email_addresses.is_a?(Array)
+
+      return @email_addresses if @email_addresses
+
+      association_class = ContextIO::API::AssociationHelpers.class_for_association_name(:email_addresses)
+
+      reconstructed_email_hashes = api_attributes['email_addresses'].collect do |addy|
+        {'email' => addy}
+      end
+
+      @email_addresses = association_class.new(
+        api,
+        self.class.association_name => self,
+        attribute_hashes: reconstructed_email_hashes
+      )
+    end
+
+    # @!attribute [r] created_at
+    #   @return [Time] The time this account was created (with Context.IO).
+    def created_at
+      @created_at ||= Time.at(created)
+    end
+
+    # @!attribute [r] suspended_at
+    #   @return [Time] The time this account was suspended.
+    def suspended_at
+      return @suspended_at if instance_variable_defined?(:@suspended_at)
+
+      @suspended_at = suspended == 0 ? nil : Time.at(suspended)
+
+      @suspended_at
+    end
+
+    # @!attribute [r] suspended?
+    #   @return [Boolean] Whether this account is currently suspended.
+    def suspended?
+      !!suspended_at
+    end
+
+    # @!attribute [r] password_expired_at
+    #   @return [Time] The time this account's password expired.
+    def password_expired_at
+      return @password_expired_at if instance_variable_defined?(:@password_expired_at)
+
+      @password_expired_at = password_expired == 0 ? nil : Time.at(password_expired)
+
+      @password_expired_at
+    end
+
+    # @!attribute [r] password_expired?
+    #   @return [Boolean] Whether this account's password is expired.
+    def password_expired?
+      !!password_expired_at
+    end
+
+    # Updates the account.
+    #
+    # @param [Hash{String, Symbol => String}] options You can update first_name
+    #   or last_name (or both).
+    def update(options={})
+      first_name = options[:first_name] || options['first_name']
+      last_name = options[:last_name] || options['last_name']
+
+      attrs = {}
+      attrs[:first_name] = first_name if first_name
+      attrs[:last_name] = last_name if last_name
+
+      return nil if attrs.empty?
+
+      it_worked = api.request(:post, resource_url, attrs)['success']
+
+      if it_worked
+        @first_name = first_name || @first_name
+        @last_name = last_name || @last_name
+      end
+
+      it_worked
+    end
+
+    def sync_data
+      return @sync_data if @sync_data
+
+      sync_hashes = api.request(:get, "#{resource_url}/sync")
+
+      @sync_data = ContextIO::AccountSyncData.new(sync_hashes)
+
+      return @sync_data
+    end
+
+    def sync!
+      api.request(:post, "#{resource_url}/sync")['success']
+    end
+
+    def delete
+      api.request(:delete, resource_url)['success']
+    end
+  end
+end

data/lib/contextio/account_collection.rb

@@ -0,0 +1,57 @@
+require_relative 'api/resource_collection'
+require_relative 'account'
+
+class ContextIO
+  # Represents a collection of email accounts for your Context.IO account. You
+  # can use this to add a new one to your account, iterate over them, or fetch a
+  # specific one.
+  #
+  # You can also limit which accounts belongin the collection using the `where`
+  # method. Valid keys are: email, status, status_ok, limit and offset. See
+  # [the Context.IO documentation](http://context.io/docs/2.0/accounts#get) for
+  # more explanation of what each key means.
+  #
+  # @example You can iterate over them with `each`:
+  #   contextio.accounts.each do |accounts|
+  #     puts account.email_addresses
+  #   end
+  #
+  # @example You can lazily access a specific one with square brackets:
+  #   account = contextio.accounts['some id']
+  #
+  # @example Lazily limit based on a hash of criteria with `where`:
+  #   disabled_accounts = contextio.accounts.where(status: 'DISABLED')
+  class AccountCollection
+    include ContextIO::API::ResourceCollection
+
+    self.resource_class = ContextIO::Account
+    self.association_name = :accounts
+
+    # Creates a new email account for your Context.IO account.
+    #
+    # @param [Hash{String, Symbol => String}] options Information you can
+    #   provide at creation: email, first_name and/or last_name. If the
+    #   collection isn't already limited by email, then you must provide it.
+    #
+    # @return [Account] A new email account instance based on the data you
+    #   input.
+    def create(options={})
+      email = options.delete(:email) || options.delete('email') ||
+        where_constraints[:email] || where_constraints['email']
+
+      if email.nil?
+        raise ArgumentError, "You must provide an email for new Accounts."
+      end
+
+      result_hash = api.request(
+        :post,
+        resource_url,
+        options.merge(email: email)
+      )
+
+      result_hash.delete('success')
+
+      resource_class.new(api, result_hash)
+    end
+  end
+end

data/lib/contextio/account_sync_data.rb

@@ -0,0 +1,22 @@
+require_relative 'source_sync_data'
+
+class ContextIO
+  class AccountSyncData
+    attr_reader :source_labels, :sources
+
+    def initialize(source_hash)
+      @source_hash = source_hash
+      @source_labels = source_hash.keys
+
+      @sources = source_hash.collect do |source_label, folder_hash|
+        ContextIO::SourceSyncData.new(source_label, folder_hash)
+      end
+    end
+  end
+
+  private
+
+  def source_hash
+    @source_hash
+  end
+end

data/lib/contextio/api.rb

@@ -0,0 +1,162 @@
+require 'uri'
+require 'oauth'
+require 'json'
+
+require 'contextio/api/url_builder'
+
+class ContextIO
+  # **For internal use only.** Users of this gem should not be using this
+  # directly.  Represents the handle on the Context.IO API. It handles the
+  # user's OAuth credentials with Context.IO and signing requests, etc.
+  class API
+    # For differentiating API errors from other errors that might happen during
+    # requests.
+    class Error < StandardError; end
+
+    # @private
+    VERSION = '2.0'
+
+    # @return [String] The version of the Context.IO API this version of the
+    #   gem is intended for use with.
+    def self.version
+      VERSION
+    end
+
+    # @private
+    BASE_URL = 'https://api.context.io'
+
+    # @return [String] The base URL the API is served from.
+    def self.base_url
+      BASE_URL
+    end
+
+    # @param [Object] resource The resource you want the URL for.
+    #
+    # @return [String] The URL for the resource in the API.
+    def self.url_for(resource)
+      ContextIO::API::URLBuilder.url_for(resource)
+    end
+
+    # @param [Object] resource The resource you want the URL for.
+    #
+    # @return [String] The URL for the resource in the API.
+    def url_for(resource)
+      ContextIO::API.url_for(resource)
+    end
+
+    def self.user_agent_string
+      "contextio-ruby-#{ContextIO.version}"
+    end
+
+    def user_agent_string
+      self.class.user_agent_string
+    end
+
+    # @!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.
+    attr_reader :key, :secret
+
+    # @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.
+    def initialize(key, secret)
+      @key = key
+      @secret = secret
+    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 = {})
+      "/#{API.version}/#{API.strip_resource_path(resource_path)}#{API.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 = token.send(method, path(resource_path, params), 'Accept' => 'application/json', 'User-Agent' => user_agent_string)
+      body = response.body
+
+      results = JSON.parse(body) unless response.body.empty?
+
+      if response.code =~ /[45]\d\d/
+        if results.is_a?(Hash) && results['type'] == 'error'
+          message = results['value']
+        else
+          message = response.message
+        end
+
+        raise API::Error, message
+      end
+
+      results
+    end
+
+    def raw_request(method, resource_path, params={})
+      response = token.send(method, path(resource_path, params), 'User-Agent' => user_agent_string)
+
+      if response.code =~ /[45]\d\d/
+        raise API::Error, response.message
+      end
+
+      response.body
+    end
+
+    private
+
+    # 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 self.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] consumer
+    # @return [OAuth::Consumer] An Oauth consumer object for credentials
+    #   purposes.
+    def consumer
+      @consumer ||= OAuth::Consumer.new(key, secret, site: API.base_url)
+    end
+
+    # @!attribute [r] token
+    # @return [Oauth::AccessToken] An Oauth token object for credentials
+    #   purposes.
+    def token
+      @token ||= OAuth::AccessToken.new(consumer)
+    end
+  end
+end

data/lib/contextio/api/association_helpers.rb

@@ -0,0 +1,17 @@
+class ContextIO
+  class 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

data/lib/contextio/api/resource.rb

@@ -0,0 +1,230 @@
+require_relative 'association_helpers'
+
+class ContextIO
+  class API
+    # When `include`d into a class, this module provides some helper methods for
+    # various things a singular resource will need or find useful.
+    module Resource
+      # (see ContextIO#api)
+      attr_reader :api
+
+      # @private
+      #
+      # For internal use only. Users of this gem shouldn't be calling this
+      # directly.
+      #
+      # @param [API] api A handle on the Context.IO API.
+      # @param [Hash{String, Symbol => String, Numeric, Boolean}] options A Hash
+      #   of attributes describing the resource.
+      def initialize(api, options = {})
+        validate_options(options)
+
+        @api = api
+
+        options.each do |key, value|
+          key = key.to_s.gsub('-', '_')
+
+          if self.class.associations.include?(key.to_sym) && value.is_a?(Array)
+            association_class = ContextIO::API::AssociationHelpers.class_for_association_name(key.to_sym)
+
+            value = association_class.new(api, self.class.association_name => self, attribute_hashes: value)
+          end
+
+          instance_variable_set("@#{key}", value)
+
+          unless self.respond_to?(key)
+            define_singleton_method(key) do
+              instance_variable_get("@#{key}")
+            end
+          end
+        end
+      end
+
+      # @!attribute [r] resource_url
+      # @return [String] The URL that will fetch attributes from the API.
+      def resource_url
+        @resource_url ||= api.url_for(self)
+      end
+
+      # Deletes the resource.
+      #
+      # @return [Boolean] Whether the deletion worked or not.
+      def delete
+        api.request(:delete, resource_url)['success']
+      end
+
+      # @!attribute [r] api_attributes
+      # @return [{String => Numeric, String, Hash, Array, Boolean}] The
+      #   attributes returned from the API as a Hash. If it hasn't been
+      #   populated, it will ask the API and populate it.
+      def api_attributes
+        @api_attributes ||= fetch_attributes
+      end
+
+      # @!attribute [r] primary_key
+      # @return [String, Symbol] The name of the key used to build the resource
+      #   URL.
+      def primary_key
+        self.class.primary_key
+      end
+
+      private
+
+      # Make sure a Resource has the declarative syntax handy.
+      def self.included(other_mod)
+        other_mod.extend(DeclarativeClassSyntax)
+      end
+
+      # Raises ArgumentError unless the primary key or the resource URL is
+      # supplied. Use this to ensure that the initializer has or can build the
+      # right URL to fetch its self.
+      #
+      # @param [Hash] options_hash The hash of options to validate.
+      def validate_options(options_hash)
+        required_keys = ['resource_url', :resource_url]
+
+        unless self.primary_key.nil?
+          required_keys << primary_key.to_s
+          required_keys << primary_key.to_sym
+        end
+
+        if (options_hash.keys & required_keys).empty?
+          raise ArgumentError, "Required option missing. Make sure you have either resource_url or #{primary_key}."
+        end
+      end
+
+      # Fetches attributes from the API for the resource. Relies on having a
+      # handle on a `ContextIO::API` via an `api` method and on a `resource_url`
+      # method that returns the path for the resource.
+      #
+      # Defines getter methods for any attributes that come back and don't
+      # already have them. This way, if the API expands, the gem will still let
+      # users get attributes we didn't explicitly declare as lazy.
+      #
+      # @return [{String => Numeric, String, Hash, Array, Boolean}] The
+      #   attributes returned from the API as a Hash. If it hasn't been
+      #   populated, it will ask the API and populate it.
+      def fetch_attributes
+        api.request(:get, resource_url).inject({}) do |memo, (key, value)|
+          key = key.to_s.gsub('-', '_')
+
+          unless respond_to?(key)
+            self.define_singleton_method(key) do
+              value
+            end
+          end
+
+          memo[key] = value
+
+          memo
+        end
+      end
+
+      # This module contains helper methods for `API::Resource`s' class
+      # definitions. It gets `extend`ed into a class when `API::Resource` is
+      # `include`d.
+      module DeclarativeClassSyntax
+        def primary_key
+          @primary_key
+        end
+
+        # @!attribute [r] association_name
+        #   @return [Symbol] The association name registered for this resource.
+        def association_name
+          @association_name
+        end
+
+        # @!attribute [r] associations
+        #   @return [Array<String] An array of the belong_to associations for
+        #     the collection
+        def associations
+          @associations ||= []
+        end
+
+        private
+
+        # Declares the primary key used to build the resource URL. Consumed by
+        # `Resource#validate_options`.
+        #
+        # @param [String, Symbol] key Primary key name.
+        def primary_key=(key)
+          @primary_key = key
+        end
+
+        # Declares the association name for the resource.
+        #
+        # @param [String, Symbol] association_name The name.
+        def association_name=(association_name)
+          @association_name = association_name.to_sym
+          ContextIO::API::AssociationHelpers.register_resource(self, @association_name)
+        end
+
+        # Declares a list of attributes to be lazily loaded from the API. Getter
+        # methods are written for each attribute. If the user asks for one and
+        # the object in question doesn't have it already, then it will look for
+        # it in the api_attributes Hash.
+        #
+        # @example an example of the generated methods
+        #   def some_attribute
+        #     return @some_attribute if instance_variable_defined?(@some_attribute)
+        #     api_attributes["some_attribute"]
+        #   end
+        #
+        # @param [Array<String, Symbol>] attributes Attribute names.
+        def lazy_attributes(*attributes)
+          attributes.each do |attribute_name|
+            define_method(attribute_name) do
+              return instance_variable_get("@#{attribute_name}") if instance_variable_defined?("@#{attribute_name}")
+              api_attributes[attribute_name.to_s]
+            end
+          end
+        end
+
+        # Declares that this resource is related to a single instance of another
+        # resource. This related resource will be lazily created as it can be,
+        # but in some cases may cause an API call.
+        #
+        # @param [Symbol] association_name The name of the association for the
+        #   class in question. Singular classes will have singular names
+        #   registered. For instance, :message should reger to the Message
+        #   resource.
+        def belongs_to(association_name)
+          define_method(association_name) do
+            if instance_variable_get("@#{association_name}")
+              instance_variable_get("@#{association_name}")
+            else
+              association_attrs = api_attributes[association_name.to_s]
+              association_class = ContextIO::API::AssociationHelpers.class_for_association_name(association_name)
+
+              if association_attrs && !association_attrs.empty?
+                instance_variable_set("@#{association_name}", association_class.new(api, association_attrs))
+              else
+                nil
+              end
+            end
+          end
+
+          associations << association_name.to_sym
+        end
+
+        # Declares that this resource is related to a collection of another
+        # resource. These related resources will be lazily created as they can
+        # be, but in some cases may cause an API call.
+        #
+        # @param [Symbol] association_name The name of the association for the
+        #   class in question. Collection classes will have plural names
+        #   registered. For instance, :messages should reger to the
+        #   MessageCollection resource.
+        def has_many(association_name)
+          define_method(association_name) do
+            association_class = ContextIO::API::AssociationHelpers.class_for_association_name(association_name)
+
+            instance_variable_get("@#{association_name}") || instance_variable_set("@#{association_name}", association_class.new(api, self.class.association_name => self, attribute_hashes: api_attributes[association_name.to_s]))
+          end
+
+          associations << association_name.to_sym
+        end
+      end
+    end
+  end
+end