contextio-lite 0.0.2

data/lib/contextio/api/resource.rb

@@ -0,0 +1,248 @@
+require_relative 'association_helpers'
+
+module ContextIO
+  module 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
+
+      # @!attribute [r] with_constraints
+      #   A Hash of the constraints limiting this resource.
+      attr_reader :with_constraints
+
+      # @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 = {})
+        @options ||= options
+        validate_options
+        @with_constraints = @options[:with] || {}
+
+        @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
+
+
+      def with(constraints)
+        constraints.each{|i,c| constraints[i] = (c ? 1 : 0) if c == !!c }
+        self.class.new(api, @options.merge(with: with_constraints.merge(constraints)))
+      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.
+      def validate_options
+        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.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, with_constraints).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_defined?("@#{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

data/lib/contextio/api/resource_collection.rb

@@ -0,0 +1,193 @@
+module ContextIO
+  module API
+    # When `include`d into a class, this module provides some helper methods for
+    # various things a collections of resources will need or find useful.
+    module ResourceCollection
+      include Enumerable
+
+      # (see ContextIO#api)
+      attr_reader :api
+
+      # @!attribute [r] where_constraints
+      #   A Hash of the constraints limiting this collection of resources.
+      attr_reader :where_constraints
+
+      # @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] options Optional params for the collection.
+      # @option options [Hash{Symbol => String, Numeric}] :where Where
+      #   constraints that limit the resources that belong to this collection.
+      # @option options [Array<Hash>] :attribute_hashes An array of hashes
+      #   describing the resources in this collection.
+      def initialize(api, options={})
+        @api = api
+        @where_constraints = options[:where] || {}
+        @attribute_hashes = options[:attribute_hashes]
+
+        self.class.associations.each do |association_name|
+          instance_variable_set("@#{association_name}", options[association_name.to_sym])
+        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
+
+      # Iterates over the resources in question.
+      #
+      # @example
+      #   contextio.connect_tokens.each do |connect_token|
+      #     puts connect_token.email
+      #   end
+      def each(&block)
+        attribute_hashes.each do |attribute_hash|
+          yield resource_class.new(api, attribute_hash.merge(associations_hash))
+        end
+      end
+
+      # Returns the number of elements in self. May be zero.
+      #
+      # @note Calling this method will load the collection if not already loaded.
+      def size
+        attribute_hashes.size
+      end
+      alias :length :size
+      alias :count :size
+
+      # Returns true if self contains no elements.
+      #
+      # @note Calling this method will load the collection if not already loaded.
+      def empty?
+        size == 0
+      end
+
+      # Specify one or more constraints for limiting resources in this
+      # collection. See individual classes in the
+      # [Context.IO docs](http://context.io/docs/2.0/) for the list of valid constraints.
+      # Not all collections have valid where constraints at all.
+      #
+      # This can be chained at need and doesn't actually cause the API to get
+      # hit until some iterator is called like `#each`.
+      #
+      # @example
+      #   accounts = contextio.accounts
+      #   accounts = accounts.where(email: 'some@email.com')
+      #   accounts = accounts.where(status: 'OK')
+      #
+      #   accounts.each do |account|
+      #     # API gets hit for this call
+      #   end
+      #
+      # @param [Hash{String, Symbol => String, Integer}] constraints A Hash
+      #   mapping keys to the desired limiting values.
+      def where(constraints)
+        constraints.each{|i,c| constraints[i] = (c ? 1 : 0) if c == !!c }
+        self.class.new(api, associations_hash.merge(where: where_constraints.merge(constraints)))
+      end
+
+      # Returns a resource with the given key.
+      #
+      # This is a lazy method, making no requests. When you try to access
+      # attributes on the object, or otherwise interact with it, it will actually
+      # make requests.
+      #
+      # @example
+      #   provider = contextio.oauth_providers['1234']
+      #
+      # @param [String] key The Provider Consumer Key for the
+      #   provider you want to interact with.
+      def [](key)
+        resource_class.new(api, associations_hash.merge(resource_class.primary_key => key))
+      end
+
+      private
+
+      # @!attribute [r] attribute_hashes
+      #   @return [Array<Hash>] An array of attribute hashes that describe, at
+      #     least partially, the objects in this collection.
+      def attribute_hashes
+        @attribute_hashes ||= api.request(:get, resource_url, where_constraints)
+      end
+
+      # @!attribute [r] associations_hash
+      #   @return [Hash{Symbol => Resource}] A hash of association names to the
+      #     associated resource of that type.
+      def associations_hash
+        @associations_hash ||= self.class.associations.inject({}) do |memo, association_name|
+          if (association = self.send(association_name))
+            memo[association_name.to_sym] = association
+          end
+
+          memo
+        end
+      end
+
+      # Make sure a ResourceCollection has the declarative syntax handy.
+      def self.included(other_mod)
+        other_mod.extend(DeclarativeClassSyntax)
+      end
+
+      # This module contains helper methods for `API::ResourceCollection`s'
+      # class definitions. It gets `extend`ed into a class when
+      # `API::ResourceCollection` is `include`d.
+      module DeclarativeClassSyntax
+        # @!attribute [r] associations
+        #   @return [Array<String] An array of the belong_to associations for
+        #     the collection
+        def associations
+          @associations ||= []
+        end
+
+        # @!attribute [r] association_name
+        #   @return [Symbol] The association name registered for this resource.
+        def association_name
+          @association_name
+        end
+
+        private
+
+        # Declares which class the `ResourceCollection` is intended to wrap. For
+        # best results, this should probably be a `Resource`. It defines an
+        # accessor for this class on instances of the collection, which is
+        # private. Make sure your collection class has required the file with
+        # the defeniiton of the class it wraps.
+        #
+        # @param [Class] klass The class that the collection, well, collects.
+        def resource_class=(klass)
+          define_method(:resource_class) do
+            klass
+          end
+        end
+
+        # Declares which class, if any, the collection belongs to. It defines an
+        # accessor for the belonged-to object.
+        #
+        # @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
+            instance_variable_get("@#{association_name}")
+          end
+
+          associations << association_name
+        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
+      end
+    end
+  end
+end

data/lib/contextio/lite.rb

@@ -0,0 +1,43 @@
+module ContextIO
+  class Lite
+    include ContextIO
+
+
+    # Creates a new `ContextIO` instance and makes a new handle for the API.
+    # This is your entry point to your Context.IO account.  For a web app, you
+    # probably want to instantiate this in some kind of initializer and keep it
+    # around for the life of the process.
+    #
+    # @param [String] key Your OAuth consumer key for your Context.IO account
+    # @param [String] secret Your OAuth consumer secret for your Context.IO
+    #   account
+    # @param [Hash] opts Optional options for OAuth connections. ie. :timeout and :open_timeout are supported
+    def initialize(key, secret, opts={})
+      @api = API.new(key, secret, opts)
+    end
+
+    # Your entry point for dealing with users.
+    #
+    # @return [Users] Allows you to work with the email accounts for
+    #   your account as a group.
+    def users
+      UserCollection.new(api)
+    end
+  end
+end
+
+require_relative 'api/association_helpers'
+require_relative 'api/resource'
+require_relative 'api/resource_collection'
+
+require_relative 'lite/api'
+require_relative 'lite/email_account'
+require_relative 'lite/email_account_collection'
+require_relative 'lite/folder'
+require_relative 'lite/folder_collection'
+require_relative 'lite/message'
+require_relative 'lite/message_collection'
+require_relative 'lite/user'
+require_relative 'lite/user_collection'
+require_relative 'lite/webhook'
+require_relative 'lite/webhook_collection'