contextio 0.5.0 → 1.0.0

data/lib/contextio/api/resource_collection.rb

@@ -0,0 +1,174 @@
+require_relative 'association_helpers'
+
+class ContextIO
+  class 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
+
+      # Specify one or more constraints for limiting resources in this
+      # collection. See individual classes 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)
+        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, 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|
+          memo[association_name.to_sym] = self.send(association_name)
+          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/api/url_builder.rb

@@ -0,0 +1,153 @@
+require 'contextio/connect_token_collection'
+require 'contextio/oauth_provider_collection'
+require 'contextio/email_settings'
+require 'contextio/account_collection'
+require 'contextio/source_collection'
+require 'contextio/folder_collection'
+require 'contextio/message_collection'
+require 'contextio/body_part_collection'
+require 'contextio/thread_collection'
+require 'contextio/webhook_collection'
+require 'contextio/email_address_collection'
+require 'contextio/contact_collection'
+require 'contextio/file_collection'
+
+class ContextIO
+  class API
+    class URLBuilder
+      class Error < StandardError; end
+
+      # Tells you the right URL for a resource to fetch attributes from.
+      #
+      # @param [ContextIO::Resource, ContextIO::ResourceCollection] resource The
+      #   resource or resource collection.
+      #
+      # @return [String] The path for that resource in the API.
+      def self.url_for(resource)
+        if (builder = @registered_urls[resource.class])
+          builder.call(resource)
+        else
+          raise Error, "URL could not be built for unregistered Class: #{resource.class}."
+        end
+      end
+
+      # Register a block that calculates the URL for a given resource.
+      #
+      # @param [Class] resource_class The class of the resource you are
+      #   registering.
+      # @param [Block] block The code that will compute the url for the
+      #   resource. This is actually a path. Start after the version number of
+      #   the API in the URL. When a URL is being calculated for a specific
+      #   resource, the resource instance will be yielded to the block.
+      #
+      # @example For Accounts
+      #   register_url ContextIO::Account do |account|
+      #     "accounts/#{account.id}"
+      #   end
+      def self.register_url(resource_class, &block)
+        @registered_urls ||= {}
+        @registered_urls[resource_class] = block
+      end
+
+      register_url ContextIO::ConnectToken do |connect_token|
+        if connect_token.account && connect_token.account.id
+          "accounts/#{connect_token.account.id}/connect_tokens/#{connect_token.token}"
+        else
+          "connect_tokens/#{connect_token.token}"
+        end
+      end
+
+      register_url ContextIO::ConnectTokenCollection do |connect_tokens|
+        if connect_tokens.account && connect_tokens.account.id
+          "accounts/#{connect_tokens.account.id}/connect_tokens"
+        else
+          'connect_tokens'
+        end
+      end
+
+      register_url ContextIO::OAuthProvider do |oauth_provider|
+        "oauth_providers/#{oauth_provider.provider_consumer_key}"
+      end
+
+      register_url ContextIO::OAuthProviderCollection do
+        'oauth_providers'
+      end
+
+      register_url ContextIO::EmailSettings do
+        'discovery'
+      end
+
+      register_url ContextIO::Account do |account|
+        "accounts/#{account.id}"
+      end
+
+      register_url ContextIO::AccountCollection do
+        'accounts'
+      end
+
+      register_url ContextIO::Source do |source|
+        "accounts/#{source.account.id}/sources/#{source.label}"
+      end
+
+      register_url ContextIO::SourceCollection do |sources|
+        "accounts/#{sources.account.id}/sources"
+      end
+
+      register_url ContextIO::FolderCollection do |folders|
+        "accounts/#{folders.source.account.id}/sources/#{folders.source.label}/folders"
+      end
+
+      register_url ContextIO::Message do |message|
+        "accounts/#{message.account.id}/messages/#{message.message_id}"
+      end
+
+      register_url ContextIO::MessageCollection do |messages|
+        "accounts/#{messages.account.id}/messages"
+      end
+
+      register_url ContextIO::BodyPartCollection do |parts|
+        "accounts/#{parts.message.account.id}/messages/#{parts.message.message_id}/body"
+      end
+
+      register_url ContextIO::Thread do |thread|
+        "accounts/#{thread.account.id}/threads/#{thread.gmail_thread_id}"
+      end
+
+      register_url ContextIO::ThreadCollection do |threads|
+        "accounts/#{threads.account.id}/threads"
+      end
+
+      register_url ContextIO::Webhook do |webhook|
+        "accounts/#{webhook.account.id}/webhooks/#{webhook.webhook_id}"
+      end
+
+      register_url ContextIO::WebhookCollection do |webhooks|
+        "accounts/#{webhooks.account.id}/webhooks"
+      end
+
+      register_url ContextIO::EmailAddress do |email_address|
+        "accounts/#{email_address.account.id}/email_addresses/#{email_address.email}"
+      end
+
+      register_url ContextIO::EmailAddressCollection do |email_addresses|
+        "accounts/#{email_addresses.account.id}/email_addresses"
+      end
+
+      register_url ContextIO::Contact do |contact|
+        "accounts/#{contact.account.id}/contacts/#{contact.email}"
+      end
+
+      register_url ContextIO::ContactCollection do |contacts|
+        "accounts/#{contacts.account.id}/contacts"
+      end
+
+      register_url ContextIO::File do |file|
+        "accounts/#{file.account.id}/files/#{file.file_id}"
+      end
+
+      register_url ContextIO::FileCollection do |files|
+        "accounts/#{files.account.id}/files"
+      end
+    end
+  end
+end

data/lib/contextio/body_part.rb

@@ -0,0 +1,45 @@
+require 'contextio/api/association_helpers'
+
+class ContextIO
+  class BodyPart
+    def self.association_name
+      :body_part
+    end
+    ContextIO::API::AssociationHelpers.register_resource(self, :body_part)
+
+    # (see ContextIO#api)
+    attr_reader :api, :message, :type, :charset, :delsp, :format, :content,
+                :body_section
+
+    # @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 = {})
+      @api = api
+      @message = options.delete(:message) || options.delete('message')
+
+      options.each do |key, value|
+        instance_variable_set("@#{key}", value)
+
+        unless self.respond_to?(key)
+          define_singleton_method(key) do
+            instance_variable_get("@#{key}")
+          end
+        end
+      end
+    end
+
+    def html?
+      type == 'text/html'
+    end
+
+    def plain_text?
+      type == 'text/plain'
+    end
+  end
+end

data/lib/contextio/body_part_collection.rb

@@ -0,0 +1,13 @@
+require_relative 'api/resource_collection'
+require_relative 'body_part'
+
+class ContextIO
+  class BodyPartCollection
+    include ContextIO::API::ResourceCollection
+
+    self.resource_class = ContextIO::BodyPart
+    self.association_name = :body_parts
+
+    belongs_to :message
+  end
+end

data/lib/contextio/connect_token.rb

@@ -0,0 +1,57 @@
+require 'contextio/api/resource'
+
+class ContextIO
+  # Represents a single connect token for an account. You can use this to
+  # inspect or delete the token. Most of the attributes are lazily loaded,
+  # meaning that the API won't get hit until you ask for an attribute the object
+  # doesn't already have (presumably from a previous API call).
+  class ConnectToken
+    include API::Resource
+
+    self.primary_key = :token
+    self.association_name = :connect_token
+
+    # @!attribute [r] account
+    #
+    # @return [ContextIO::Account, nil] The Account associated with this token,
+    #   if any. Will fetch from the API if necessary.
+    belongs_to :account
+
+    # @!attribute [r] token
+    #   @return [String] The token associated with this connect token. Will
+    #     fetch from the API if necessary.
+    # @!attribute [r] email
+    #   @return [String] The email address associated with this token. Will
+    #     fetch from the API if necessary.
+    # @!attribute [r] used
+    #   @return [Boolean] Whether this token has been used ot not. Will fetch
+    #     from the API if necessary.
+    # @!attribute [r] callback_url
+    #   @return [String] The url that Context.IO will redirect the user to when
+    #     the account is created. Will fetch from the API if necessary.
+    # @!attribute [r] service_level
+    #   @return [String] The Context.IO service level for this account. Will
+    #     fetch from the API if necessary.
+    # @!attribute [r] first_name
+    #   @return [String] The first name of the owner of the email account
+    #     associated with this token. Will fetch from the API if necessary.
+    # @!attribute [r] last_name
+    #   @return [String] The last name of the owner of the email account
+    #     associated with this token. Will fetch from the API if necessary.
+    lazy_attributes :token, :email, :created, :used, :callback_url,
+                    :service_level, :first_name, :last_name
+    private :created
+
+    # @!attribute [r] created_at
+    #
+    # @return [Time] The time this token was created. Will fetch from the API
+    #   if necessary.
+    def created_at
+      @created_at ||= Time.at(created)
+    end
+
+    def delete
+      api.request(:delete, resource_url)['success']
+    end
+  end
+end

data/lib/contextio/connect_token_collection.rb

@@ -0,0 +1,44 @@
+require_relative 'connect_token'
+require_relative 'api/resource_collection'
+
+class ContextIO
+  # Represents a collection of connect tokens for your account. You can use this
+  # to create a new token, fetch a specific one or iterate over them.
+  #
+  # @example You can iterate over them with `each`:
+  #   contextio.connect_tokens.each do |connect_token|
+  #     puts connect_token.email
+  #   end
+  #
+  # @example You can lazily access a specific one with square brackets:
+  #   connect_token = contextio.connect_tokens['some_token']
+  class ConnectTokenCollection
+    include ContextIO::API::ResourceCollection
+
+    self.resource_class = ContextIO::ConnectToken
+    self.association_name = :connect_tokens
+
+    belongs_to :account
+
+    # Creates a new connect token for your account.
+    #
+    # @param [String] callback_url The url that the user will be redirected to
+    #   after OAuthing their account with Context.IO.
+    # @param [Hash{String, Symbol => String}] options Optional information you
+    #   can provide at creation: email, service level, first_name and/or
+    #   last_name.
+    #
+    # @return [ConnectToken] A new token instance based on the data you input.
+    def create(callback_url, options={})
+      result_hash = api.request(
+        :post,
+        resource_url,
+        options.merge(callback_url: callback_url)
+      )
+
+      result_hash.delete('success')
+
+      resource_class.new(api, result_hash)
+    end
+  end
+end