verticalresponse 0.1.1

data/README.md

@@ -0,0 +1,4 @@
+VerticalResponse
+================
+
+Gem used to make it easier to connect to VerticalResponse.com's API

data/lib/client.rb

@@ -0,0 +1,112 @@
+# This is the base class for the VerticalResponse API.
+# It contains common functionality that other classes can use to connect to the
+# API and make REST calls to it.
+
+require 'httparty'
+require_relative 'response'
+
+module VerticalResponse
+  module API
+    class Client
+      include HTTParty
+
+      format :json
+
+      class << self
+        def config
+          VerticalResponse::CONFIG
+        end
+
+        # Assign the headers required by our partner Mashery
+        def assign_headers(headers_info = {})
+          access_token = headers_info[:access_token]
+          add_default_query_param(:access_token, access_token)
+        end
+
+        def embed_resource(resource, resource_id = nil)
+          @embed_resource = resource
+          @embed_resource_id = resource_id if resource_id
+        end
+
+        # Returns the base URI of the VerticalResponse API.
+        # It builds the URI based on the values from the API configuration file.
+        # 'host' must be defined (unless host_uri is specified as an input param)
+        # otherwise the method will raise an exception.
+        def base_uri(host_uri = nil)
+          uri = host_uri
+          unless uri
+            unless VerticalResponse::CONFIG[:host]
+              raise ConfigurationError, 'Configuration option "host" must be defined.'
+            end
+
+            uri = URI::Generic.new(
+              VerticalResponse::CONFIG[:protocol] || 'http', # protocol scheme
+              nil,                          # user info
+              VerticalResponse::CONFIG[:host],               # host
+              VerticalResponse::CONFIG[:port],               # port
+              nil,                          # registry of naming authorities
+              nil,                          # path on server
+              nil,                          # opaque part
+              nil,                          # query data
+              nil                           # fragment (part of URI after '#' sign)
+            )
+          end
+
+          paths = ['api', 'v1']
+          paths << @embed_resource.to_s if @embed_resource
+          paths << @embed_resource_id.to_s if @embed_resource_id
+          URI.join(uri, File.join(*paths))
+        end
+
+        def build_params(params, query_params = {})
+          request_params = {}
+          request_params[:body] = params if params
+          # Add whatever query params we have as well
+          request_params.merge(build_query_params(query_params))
+        end
+
+        def build_query_params(params = {})
+          query_params = {}
+          # Include the default query params
+          params = params.merge(default_query_params)
+          query_params[:query] = params if params.any?
+          query_params
+        end
+
+        def default_query_params
+          @@default_query_params ||= {}
+        end
+
+        def add_default_query_param(param, value)
+          @@default_query_params ||= {}
+          @@default_query_params[param] = value
+        end
+
+        # Resource URI for the current class
+        def resource_uri(*additional_paths)
+          uri = base_uri
+          if additional_paths.any?
+            # Convert all additional paths to string
+            additional_paths = additional_paths.map do |path|
+              # We need to escape each path in case it contains caracters that
+              # are not appropriate to use as part of an URL.
+              # Unescape and then escape again in case the path is already escaped
+              URI::escape(URI::unescape(path.to_s))
+            end
+            uri = File.join(uri, *additional_paths)
+          end
+          uri
+        end
+      end
+
+      # Set default headers for OAuth authentication
+      assign_headers
+
+      attr_accessor :response
+
+      def initialize(response)
+        self.response = response
+      end
+    end
+  end
+end

data/lib/contact.rb

@@ -0,0 +1,43 @@
+# Class that represents a contact resource from the VerticalResponse API.
+# It has the ability to make REST calls to the API, as well as to wrap
+# the contact objects we get as response.
+#
+# NOTE: This class does not necessarily include all the available methods
+# the API has for the contact resource. You can consider this an initial
+# approach for an object oriented solution that you can expand according to
+# your needs.
+
+require_relative 'message'
+
+module VerticalResponse
+  module API
+    class Contact < Resource
+      class << self
+        # Base URI for the Contact resource
+        def base_uri(*args)
+          @base_uri ||= File.join(super.to_s, 'contacts')
+        end
+
+        def fields(options = {})
+          Response.new get(resource_uri('fields'), build_query_params(options))
+        end
+      end
+
+      def initialize(*args)
+        super
+        @list_class = self.class.class_for_resource(List, id)
+        @message_class = self.class.class_for_resource(Message, id)
+      end
+
+      # Returns all the lists this contact belongs to
+      def lists(options = {})
+        @list_class.all(options)
+      end
+
+      # Returns all the messages targetted to the current contact
+      def messages(options = {})
+        @message_class.all(options)
+      end
+    end
+  end
+end

data/lib/custom_field.rb

@@ -0,0 +1,30 @@
+# Class that represents a custom field resource from the VerticalResponse API.
+# It has the ability to make REST calls to the API, as well as to wrap
+# the custom field objects we get as response.
+#
+# NOTE: This class does not necessarily include all the available methods
+# the API has for the custom field resource. You can consider this an initial approach
+# for an object oriented solution that you can expand according to your needs.
+
+require_relative 'resource'
+
+module VerticalResponse
+  module API
+    class CustomField < Resource
+      class << self
+        # Base URI for the Message resource
+        def base_uri(*args)
+          @base_uri ||= File.join(super.to_s, 'custom_fields')
+        end
+
+        def id_regexp
+          /[a-z0-9 _%]{1,255}/i
+        end
+
+        def id_attribute_name
+          'name'
+        end
+      end
+    end
+  end
+end

data/lib/email.rb

@@ -0,0 +1,110 @@
+# Class that represents an email resource from the VerticalResponse API.
+# It has the ability to make REST calls to the API, as well as to wrap
+# the email objects we get as response.
+#
+# NOTE: This class does not necessarily include all the available methods
+# the API has for the email resource. You can consider this an initial approach
+# for an object oriented solution that you can expand according to your needs.
+
+require_relative 'resource'
+require_relative 'list'
+
+module VerticalResponse
+  module API
+    class Email < Resource
+      class << self
+        # Base URI for the Email resource
+        def base_uri(*args)
+          @base_uri ||= File.join(super.to_s, 'messages', 'emails')
+        end
+
+        # Overwrite from parent class since it's a special type of
+        # resource name (with messages at the beginning)
+        def resource_name
+          'messages/emails'
+        end
+
+        # The Email API does not support the 'all' method on its own for now.
+        # To get all emails we need to do it through the Message API
+        def all(options = {})
+          Message.all(options.merge({ :message_type => MESSAGE_TYPE }))
+        end
+      end
+
+      MESSAGE_TYPE = 'email'
+
+      def initialize(*args)
+        super
+        @list_class = self.class.class_for_resource(List, id)
+      end
+
+      # Returns all the lists this email is targeted to
+      def lists(options = {})
+        @list_class.all(options)
+      end
+
+      def test_launch(params = {})
+        Response.new self.class.post(
+          self.class.resource_uri(id, 'test'),
+          self.class.build_params(params)
+        )
+      end
+
+      # Launches an email and return the response object
+      def launch(params = {})
+        # Supports receiving an array of List objects (Object Oriented)
+        lists = params.delete(:lists)
+        if lists
+          params[:list_ids] ||= []
+          params[:list_ids] += lists.map do |list|
+            list.respond_to?(:id) ? list.id : list.to_i
+          end
+          # Remove duplicate IDs, if any
+          params[:list_ids].uniq!
+        end
+
+        Response.new self.class.post(
+          self.class.resource_uri(id),
+          self.class.build_params(params)
+        )
+      end
+
+      def unschedule(params = {})
+        Response.new self.class.post(
+          self.class.resource_uri(id, 'unschedule'),
+          self.class.build_params(params)
+        )
+      end
+
+      def opens_stats(options = {})
+        detailed_stat(:opens)
+      end
+
+      def clicks_stats(options = {})
+        detailed_stat(:clicks)
+      end
+
+      def unsubscribes_stats(options = {})
+        detailed_stat(:unsubscribes)
+      end
+
+      private
+
+      def detailed_stat(stat_name, options = {})
+        stat_name = stat_name.to_s
+        unless %w(opens clicks unsubscribes).include?(stat_name)
+          raise NotImplementedError,
+                "'#{stat_name}' stat is not supported for the #{class_name} class"
+        end
+
+        if response.links && response.links.has_key?(stat_name)
+          uri = response.links[stat_name]['url']
+        else
+          uri = self.class.resource_uri(id, 'stats', stat_name)
+        end
+
+        Response.new self.class.get(uri, self.class.build_query_params(options))
+      end
+    end
+  end
+end

data/lib/error.rb

@@ -0,0 +1,11 @@
+# Client errors that can be raised from VerticalResponse API response errors.
+
+module VerticalResponse
+  module API
+    class Error < StandardError
+      attr_accessor :code, :api_response
+    end
+
+    class ConfigurationError < Error; end
+  end
+end

data/lib/list.rb

@@ -0,0 +1,69 @@
+# Class that represents a list resource from the VerticalResponse API.
+# It has the ability to make REST calls to the API, as well as to wrap
+# the list objects we get as response.
+#
+# NOTE: This class does not necessarily include all the available methods
+# the API has for the list resource. You can consider this an initial approach
+# for an object oriented solution that you can expand according to your needs.
+
+require_relative 'contact'
+
+module VerticalResponse
+  module API
+    class List < Resource
+      class << self
+        # Base URI for the List resource
+        def base_uri(*args)
+          @base_uri ||= File.join(super.to_s, 'lists')
+        end
+      end
+
+      def initialize(*args)
+        super
+        @contact_class = self.class.class_for_resource(Contact, id)
+        @message_class = self.class.class_for_resource(Message, id)
+      end
+
+      # Returns all the messages targetted to the current list
+      def messages(options = {})
+        @message_class.all(options)
+      end
+
+      # Returns all the contacts that belong to the list
+      def contacts(options = {})
+        @contact_class.all(options)
+      end
+
+      def find_contact(contact_id, options = {})
+        @contact_class.find(contact_id, options)
+      end
+
+      # Creates a contact for the list with the parameters provided
+      def create_contact(params)
+        @contact_class.create(params)
+      end
+
+      # Creates contacts in batch for the list with the parameters provided
+      def create_contacts(params)
+        params = { :contacts => params } if params.is_a?(Array)
+        @contact_class.create(params)
+      end
+
+      # Deletes a contact from the list
+      def delete_contact(contact)
+        # Make a copy of the original contact but embedding the request
+        # within the list resource
+        contact_to_delete = @contact_class.new(contact.response)
+        contact_to_delete.delete
+      end
+
+      # Deletes contacts in batch from the list
+      def delete_contacts(contact_emails)
+        Response.new @contact_class.delete(
+          @contact_class.resource_uri,
+          self.class.build_params({ :contacts => contact_emails })
+        )
+      end
+    end
+  end
+end

data/lib/message.rb

@@ -0,0 +1,44 @@
+# Class that represents a message resource from the VerticalResponse API.
+# It has the ability to make REST calls to the API, as well as to wrap
+# the message objects we get as response.
+#
+# NOTE: This class does not necessarily include all the available methods
+# the API has for the message resource. You can consider this an initial approach
+# for an object oriented solution that you can expand according to your needs.
+
+require_relative 'email'
+require_relative 'social_post'
+
+module VerticalResponse
+  module API
+    class Message < Resource
+      class << self
+        # Base URI for the Message resource
+        def base_uri(*args)
+          @base_uri ||= File.join(super.to_s, 'messages')
+        end
+
+        # Overwritting this method from the parent class since we want to
+        # return object instances depending on the message type
+        def object_collection(response)
+          response.handle_collection do |response_item|
+            message_class = self
+            if response_item.attributes && response_item.attributes.has_key?('message_type')
+              type = response_item.attributes['message_type'].downcase.gsub(' ', '_')
+              if type == Email::MESSAGE_TYPE
+                message_class = Email
+              elsif type == SocialPost::MESSAGE_TYPE
+                message_class = SocialPost
+              end
+            end
+            message_class.new(response_item)
+          end
+        end
+      end
+
+      # Remove methods that are not supported by the Message API.
+      # Message only supports the 'all' method for now
+      exclude_methods :create, :find, :update, :delete, :stats
+    end
+  end
+end

data/lib/oauth.rb

@@ -0,0 +1,67 @@
+# This class provides users the ability to generate oAuth tokens for the
+# VerticalResponse API.
+#
+# Check the examples/sample code to know how to use this class.
+
+require_relative 'client'
+
+module VerticalResponse
+  module API
+    class OAuth < Client
+      # We expect HTML format as the API might redirect to a signin page or
+      # return errors in HTML format
+      format :html
+
+      def initialize(access_token)
+        @access_token = access_token
+      end
+
+      def lists
+        VerticalResponse::API::List.all({"access_token" => @access_token})
+      end
+
+      def contacts
+        VerticalResponse::API::Contact.all({"access_token" => @access_token})
+      end
+
+      def get_list(list_id)
+        VerticalResponse::API::List.find(list_id, {"access_token" => @access_token})
+      end
+
+      class << self
+        # Overwrite this method as we don't need to setup headers for
+        # OAuth calls
+        def assign_headers(*args)
+        end
+
+        # Base URI for the OAuth calls
+        def base_uri(*args)
+          @base_uri ||= File.join(super.to_s, 'oauth')
+        end
+
+        # client_id is the application key
+        def authorize(redirect_uri = "", client_id = "")
+          get(
+            resource_uri('authorize'),
+            build_query_params({ :client_id => client_id, :redirect_uri => redirect_uri })
+          )
+        end
+
+        def access_token(auth_code,
+                         redirect_uri = "",
+                         client_id = "",
+                         client_secret = "")
+          get(
+            resource_uri('access_token'),
+            build_query_params({
+              :client_id => client_id,
+              :client_secret => client_secret,
+              :code => auth_code,
+              :redirect_uri => redirect_uri
+            })
+          )
+        end
+      end
+    end
+  end
+end