active_esp 0.1.0.alpha1

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.DS_Store
+.rvmrc

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in active_esp.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Brian Morton
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,81 @@
+# ActiveESP
+
+**NOTE**: ActiveESP is still a very early project with limited support.  Be careful when using it as implementations are still changing rapidly.  Feel free to contribute and help us with our first official release!
+
+ActiveESP is an abstraction library for managing subscribers, campaigns, and other email marketing facilities. It aims to provide a consistent interface to interact with the numerous ESPs operating with different terminologies and strategies.
+
+This framework provides some common classes for managing email marketing data structures as well as the adapters for interfacing with the providers' APIs.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'active_esp'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install active_esp
+
+## Basic usage
+
+For basic usage, an instance of any of the supported providers may be instantiated and used independently by calling methods on the provider directly.
+
+```
+subscriber = ActiveESP::Subscriber.new(
+  :email => 'brian@xq3.net', 
+  :name => 'Brian Morton'
+)
+
+provider = ActiveESP::Providers::MailChimp.new(
+  :api_key => '12345678901234567890-us4'
+)
+
+list = ActiveESP::List.new(:id => '03b3b0f203')
+
+provider.subscribe(subscriber, list) # => true
+```
+
+## Configuring and using a shared provider
+
+For a better integration into an application, using a shared provider tries to hide as much of the provider's specific implementation details as it can.  After the provider is configured, as many calls as possible are genericized to work across all implementations.
+
+```
+ActiveESP.configure do |c|
+  c.provider :mail_chimp
+  c.credentials :api_key => '12345678901234567890-us4'
+end
+
+ActiveESP.provider # => #<ActiveESP::Providers::MailChimp:0x007f868b33fb30 @api_key="12345678901234567890-us4">
+```
+
+## Using convenience methods
+
+Convenience methods are defined on the basic Subscriber and List classes for sending themselves in an API request to the shared provider.  After configuring a provider, these methods can be fired on any subscriber or list object.
+
+```
+ActiveESP.configure do |c|
+  c.provider :mail_chimp
+  c.credentials :api_key => '12345678901234567890-us4'
+end
+
+member = ActiveESP::Subscriber.new(
+  :email => 'brian@xq3.net', 
+  :name => 'Brian Morton'
+)
+
+list = ActiveESP::List.new(:id => '123456')
+
+member.subscribe!(list)
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,27 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new('spec')
+
+# If you want to make this the default task
+task :default => :spec
+
+desc 'Execute a console with the environment preloaded'
+task :console do
+  exec 'irb -rubygems -I lib -r active_esp.rb'
+end
+
+namespace :docs do
+  task :generate do
+    exec 'yard doc'
+  end
+
+  task :server do
+    exec 'yard server --reload --server thin'
+  end
+
+  task :stats do
+    exec 'yard stats'
+  end
+end

data/active_esp.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/active_esp/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Brian Morton"]
+  gem.email         = ["bmorton@sdreader.com"]
+  gem.description   = %q{Framework and tools for managing email service providers.}
+  gem.summary       = %q{ActiveESP is an abstraction library for managing subscribers, campaigns, and other email marketing facilities.  It provides a consistent interface to interact with the numerous ESPs.}
+  gem.homepage      = "http://1703india.st/active_esp"
+
+  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.name          = "active_esp"
+  gem.require_paths = ["lib"]
+  gem.version       = ActiveESP::VERSION
+
+  gem.add_runtime_dependency "json", "> 1.4.0"
+  gem.add_runtime_dependency "httparty", "~> 0.8.1"
+  gem.add_runtime_dependency "activesupport", ">= 3.0.0"
+  gem.add_runtime_dependency "shuber-interface", "~> 0.0.4"
+
+  gem.add_development_dependency "rspec", "~> 2.8.0"
+  gem.add_development_dependency "factory_girl", "~> 2.5.1"
+  gem.add_development_dependency "yard", "~> 0.7.5"
+  gem.add_development_dependency "thin", "~> 1.3.1"
+  gem.add_development_dependency "redcarpet", "~> 2.1.0"
+end

data/lib/active_esp/configuration.rb

@@ -0,0 +1,125 @@
+module ActiveESP
+  module Configuration
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      # Instantiates a shared provider singleton for access through ActiveESP.provider
+      #
+      # To use the configuration method, call it with a block and specify a provider and
+      # any credentials that provider expects as a hash.
+      #
+      # == Example Usage
+      #   ActiveESP.configure do |c|
+      #     c.provider :mail_chimp
+      #     c.credentials :api_key => '12345678901234567890-us4'
+      #   end
+      #
+      # @param [Block] A block of method calls to set up a provider
+      # @return [Provider] Returns the shared provider that was instantiated due to
+      # the provided configuration
+      def configure(&block)
+        yield self
+        reset_provider
+      end
+
+      # Returns the shared provider and optionally sets up the provider with the class
+      # passed as its only argument.
+      #
+      # If a provider_class is provided, the method will set the class to use when
+      # instantiating the shared provider.  Since provider and credentials could
+      # potentially be set in any order in the configuration block, we only want
+      # to try to instantiate a provider if the credentials have already been set.
+      # If the credentials have not been set, a new provider will not be returned
+      # until the method is called after credentials have been set.
+      # 
+      # == Example Usage
+      #   ActiveESP.provider :mail_chimp # => nil
+      #
+      # If the method is called with no arguments, it will return the shared provider,
+      # instantiating it if necessary.  Again, this relies on the provider class and
+      # credentials being previously set.
+      #
+      # == Example Usage
+      #   ActiveESP.provider # => #<ActiveESP::Providers::MailChimp:0x007f868b33fb30 @api_key="test">
+      #
+      # @param [Symbol] An optional symbol representing the provider class to use
+      # @return [Provider] The shared provider object or nil if it can't be instantiated
+      def provider(provider_class = nil)
+        # If the provider hasn't been instantiated yet and we're not using this method
+        # to set the provider's class, we need to reset the provider so that it can be
+        # returned properly.
+        reset_provider if !@provider && !provider_class
+        return @provider unless provider_class
+        self.provider_class = provider_class
+      end
+
+      # Sets the shared provider to any custom instantiated provider
+      #
+      # When necessary, the configuration method can be skipped and a provider can be
+      # directly assigned to be the shared provider.
+      #
+      # == Example Usage
+      #   ActiveESP.provider = ActiveESP::Providers::MailChimp.new(
+      #     :api_key => '12345678901234567890-us4'
+      #   )
+      #
+      # @param [Provider] An instance of an object in the ActiveESP::Providers namespace
+      # @return [Provider] The passed provider object
+      def provider=(shared_provider)
+        @provider = shared_provider
+      end
+
+      # Assigns and/or returns the provider's credentials when configuring via the
+      # configuration method
+      #
+      # This is used to help the configuration method assign credentials conveniently.
+      # It works outside of the configuration block as well.
+      #
+      # == Example Usage
+      #   ActiveESP.credentials :api_key => '12345678901234567890-us4'
+      #
+      # @param [Hash] provider_credentials An optional hash of values needed to
+      # instantiate a provider object
+      # @return [Hash] The credentials required to instantiate a provider object
+      def credentials(provider_credentials = nil)
+        @credentials = provider_credentials if provider_credentials
+        @credentials
+      end
+
+      # Assigns the provider's credentials
+      #
+      # == Example Usage
+      #   ActiveESP.credentials = { :api_key => '12345678901234567890-us4' }
+      #
+      # @param [Hash] provider_credentials A hash of values needed to instantiate a
+      # provider object
+      # @return [Hash] The provided credentials
+      def credentials=(provider_credentials)
+        @credentials = provider_credentials
+      end
+
+    private
+
+      # Defines which provider class to use and resets the shared provider
+      #
+      # @return nil
+      def provider_class=(klass)
+        @provider_class = klass
+        @provider = nil
+      end
+
+      # Clears the shared provider, reinstantiates it, and returns it
+      #
+      # @return [Provider] shared provider instance
+      def reset_provider
+        begin
+          full_provider_class_name = "ActiveESP::Providers::#{@provider_class.to_s.classify}".constantize
+        rescue NameError
+          raise ActiveESP::ProviderNotSupportedException.new("#{@provider_class.to_s} is not a supported provider.")
+        end
+
+        @provider = full_provider_class_name.new(@credentials)
+      end
+    end
+  end
+end

data/lib/active_esp/inflections.rb

@@ -0,0 +1,3 @@
+ActiveSupport::Inflector.inflections do |inflect|
+  inflect.acronym 'IContact'
+end

data/lib/active_esp/list.rb

@@ -0,0 +1,42 @@
+module ActiveESP
+  class List
+    # Returns or sets the list's identifier
+    #
+    # @return [String]
+    attr_accessor :id
+
+    # Returns or sets the list's name
+    #
+    # @return [String]
+    attr_accessor :name
+
+    # Initialize object with an optional attributes hash
+    #
+    # @param [Hash] attributes An optional hash of attributes to assign to the new instance
+    def initialize(attributes = nil)
+      if attributes.is_a? Hash
+        attributes.each do |key, value|
+          self.send(key.to_s + "=", value)
+        end
+      end
+    end
+
+    # Accessing commonly used API calls
+
+    # Add the given subscriber to this list.
+    #
+    # @see ActiveESP::Providers::Interface#subscribe
+    def subscribe!(subscriber)
+      raise ActiveESP::ProviderNotConfiguredException unless ActiveESP.provider
+      ActiveESP.provider.subscribe(subscriber, self)
+    end
+
+    # Remove the given subscriber from this list.
+    #
+    # @see ActiveESP::Providers::Interface#unsubscribe
+    def unsubscribe!(subscriber)
+      raise ActiveESP::ProviderNotConfiguredException unless ActiveESP.provider
+      ActiveESP.provider.unsubscribe(subscriber, self)
+    end
+  end
+end

data/lib/active_esp/providers/base.rb

@@ -0,0 +1,51 @@
+module ActiveESP
+  # A +Provider+ in ActiveESP is an individual ESP class that implements the required
+  # methods to conform to a +Provider+ protocol.
+  #
+  # To make things work smoothly, the framework expects a +Provider+ to extend from
+  # +ActiveESP::Providers::Base+. This allows common functionality to be shared
+  # amongst the providers as well as exceptions to be raised when the provider
+  # doesn't implement a required method.
+  #
+  module Providers
+    class Base
+      implements ActiveESP::Providers::Interface
+      # Returns or sets the API key
+      #
+      # @return [String]
+      attr_accessor :api_key
+
+      # Sets the endpoint base URL without a trailing slash
+      #
+      # @return [String]
+      attr_writer :endpoint
+      cattr_accessor :endpoint
+
+      # Initialize object with an optional attributes hash
+      #
+      # @param [Hash] attributes An optional hash of attributes to assign to the new instance
+      def initialize(attributes = nil)
+        if attributes.is_a? Hash
+          attributes.each do |key, value|
+            self.send(key.to_s + "=", value)
+          end
+        end
+      end
+
+      def endpoint
+        if defined?(@endpoint)
+          @endpoint
+        elsif self.class.endpoint
+          self.class.endpoint
+        elsif superclass != Object && superclass.endpoint
+          superclass.endpoint
+        else
+          @endpoint ||= ''
+        end
+      end
+
+    end
+
+    class MethodNotImplementedException < Exception; end
+  end
+end

data/lib/active_esp/providers/icontact.rb

@@ -0,0 +1,164 @@
+module ActiveESP
+  module Providers
+    # This is the implementation for version 2.0 of iContact's API.
+    #
+    # == Example Usage
+    #   ActiveESP.configure do |c|
+    #    c.provider :icontact
+    #    c.credentials :app_id => '1234567890',
+    #                  :username => 'testuser',
+    #                  :password => 'password',
+    #                  :api_version => '2.0'
+    #  end
+    #  
+    #  list = ActiveESP::List.new(:id => 123)
+    #  subscriber = ActiveESP::Subscriber.new(
+    #    :email => 'user@example.com',
+    #    :name => 'Brian Morton'
+    #  )
+    #  
+    #  ActiveESP.provider.subscribe(subscriber, list)
+    #
+    class IContact < Base
+      include HTTParty
+      format :plain
+      self.endpoint = 'https://app.icontact.com/icp'
+
+      # Returns or sets the application ID provided by iContact
+      #
+      # @see https://app.icontact.com/icp/core/registerapp/
+      # @return [String]
+      attr_accessor :app_id
+
+      # Returns or sets the username of the account associated with
+      # the application ID.
+      #
+      # @see https://app.icontact.com/icp/core/registerapp/
+      # @see http://developer.icontact.com/documentation/authenticate-requests/
+      # @return [String]
+      attr_accessor :username
+
+      # Returns or sets the password of the username or application ID
+      # provided.
+      #
+      # @see https://app.icontact.com/icp/core/registerapp/
+      # @see http://developer.icontact.com/documentation/authenticate-requests/
+      # @return [String]
+      attr_accessor :password
+
+      # The version of the iContact API that is being accessed.
+      # 
+      # Currently only version 2.0 is supported.  This is for backporting
+      # functionality for 1.0 or supporting future versions of the API.
+      #
+      # @see http://developer.icontact.com/documentation/authenticate-requests/
+      # @return [String]
+      attr_accessor :api_version
+
+      # Interface implementation
+
+      # Create a contact and optionally subscribe them to a provided list.
+      #
+      # Note: On iContact, a user cannot be subscribed to a list that they have
+      # previously unsubscribed from.
+      #
+      # @see ActiveESP::Providers::Interface#subscribe
+      def subscribe(subscriber, list = nil)
+        response = call(:post, "/a/#{account_id}/c/#{client_folder_id}/contacts", [{:email => subscriber.email, :firstName => subscriber.first_name, :lastName => subscriber.last_name}])
+        subscriber.id = response['contacts'].first['contactId']
+        if list
+          list_response = call(:post, "/a/#{account_id}/c/#{client_folder_id}/subscriptions", [{:listId => list.id, :contactId => subscriber.id, :status => 'normal' }])
+          raise ActiveESP::Providers::CouldNotSubscribeToListException, list_response['warnings'] if list_response['warnings']
+        end
+        subscriber
+      end
+
+      # Unsubscribe a subscriber from the provided list.
+      #
+      # @see ActiveESP::Providers::Interface#unsubscribe
+      def unsubscribe(subscriber, list)
+        response = call(:post, "/a/#{account_id}/c/#{client_folder_id}/subscriptions/#{list.id}_#{subscriber.id}", :status => 'unsubscribed')
+
+        raise ActiveESP::Providers::CouldNotUnsubscribeFromListException, response['warnings'] if response['warnings']
+        raise ActiveESP::Providers::CouldNotUnsubscribeFromListException, response['errors'] if response['errors']
+      end
+
+      # Retrieve an array of lists
+      #
+      # @see ActiveESP::Providers::Interface#lists
+      def lists
+        call(:get, "/a/#{account_id}/c/#{client_folder_id}/lists")
+      end
+
+      # Getting iContact-specific account information
+
+      # Retrieves the iContact account information attached to the credentials
+      # provided.
+      #
+      # @see http://developer.icontact.com/documentation/request-your-accountid-and-clientfolderid/
+      # @return [Array] An array with hashes of the associated account information
+      def account
+        call(:get, '/a')
+      end
+
+      # Retrieves the iContact client folders for the account.
+      #
+      # @see http://developer.icontact.com/documentation/request-your-accountid-and-clientfolderid/
+      # @return [Array] An array with hashes of the client folders
+      def client_folders
+        call(:get, "/a/#{account_id}/c")
+      end
+
+      # Retrieving account information necessary for API calls
+
+      # Retrieves the account ID associated with the credentials in cases where it
+      # is not provided with the credentials.
+      #
+      # Note: You should *always* specify the account ID manually by setting
+      # account_id so that an additional API request doesn't need to be made
+      # to retrieve it.
+      #
+      # @see http://developer.icontact.com/documentation/request-your-accountid-and-clientfolderid/
+      # @return [Array] An array with hashes of the client folders
+      def account_id
+        @account_id ||= account['accounts'].first['accountId']
+      end
+      attr_writer :account_id
+
+      # Retrieves the client folder ID of the first folder returned.
+      #
+      # This ID is required to make API calls.  It is recommended that it is
+      # set with the credentials, but if it is not, an attempt will be made
+      # to determine it via an API call.
+      #
+      # Note: You should *always* specify the folder ID manually by setting
+      # client_folder_id so that an additional API request doesn't need to be
+      # made to retrieve it.
+      #
+      # @see http://developer.icontact.com/documentation/request-your-accountid-and-clientfolderid/
+      # @return [Array] An array with hashes of the client folders
+      def client_folder_id
+        @client_folder_id ||= client_folders['clientfolders'].first['clientFolderId']
+      end
+      attr_writer :client_folder_id
+
+    private
+      def call(method, resource, params = {})
+        self.class.base_uri self.endpoint
+        body = params.to_json
+        response = self.class.send(method, resource, :headers => headers, :body => body)
+
+        JSON.parse(response.body)
+      end
+
+      def headers
+        { 'Accept' => 'application/json',
+          'Content-Type' => 'application/json',
+          'API-Version' => api_version,
+          'API-AppId' => app_id,
+          'API-Username' => username,
+          'API-Password' => password }
+      end
+    end
+  end
+end

data/lib/active_esp/providers/interface.rb

@@ -0,0 +1,15 @@
+module ActiveESP
+  module Providers
+    module Interface
+      # Subscription methods
+
+      def subscribe(subscriber, list = nil); end
+      def unsubscribe(subscriber, list = nil); end
+      def subscribed?(subscriber, list = nil); end
+
+      # List methods
+      
+      def lists; end
+    end
+  end
+end

data/lib/active_esp/providers/mail_chimp.rb

@@ -0,0 +1,45 @@
+module ActiveESP
+  module Providers
+    class MailChimp < Base
+      include HTTParty
+      format :plain
+
+      def endpoint
+        "https://#{dc_from_api_key}api.mailchimp.com/1.3"
+      end
+
+      def subscribe(subscriber, list)
+        call(:list_subscribe, { :id => list.id, :email_address => subscriber.email, :merge_vars => { :FNAME => subscriber.first_name, :LNAME => subscriber.last_name }})
+      end
+
+      def lists
+        call(:lists)
+      end
+
+    private
+      def call(method, params = {})
+        api_url = endpoint + '/?method=' + method.to_s.camelize(:lower)
+        params = api_params(params)
+        response = self.class.post(api_url, :body => CGI::escape(params.to_json), :timeout => 30)
+
+        # Some calls (e.g. listSubscribe) return json fragments
+        # (e.g. true) so wrap in an array prior to parsing
+        response = JSON.parse('['+response.body+']').first
+
+        if @throws_exceptions && response.is_a?(Hash) && response["error"]
+          raise "Error from MailChimp API: #{response["error"]} (code #{response["code"]})"
+        end
+
+        response
+      end
+
+      def api_params(additional_params = {})
+        { :apikey => api_key }.merge(additional_params)
+      end
+
+      def dc_from_api_key
+        (!@api_key.present? || @api_key !~ /-/) ? '' : "#{@api_key.split("-").last}."
+      end
+    end
+  end
+end

data/lib/active_esp/providers.rb

@@ -0,0 +1,18 @@
+module ActiveESP
+  module Providers
+    # Thanks to ActiveMerchant for this autoloading code!
+    Dir[File.dirname(__FILE__) + '/providers/*.rb'].each do |f|
+      # Get camelized class name 
+      filename = File.basename(f, '.rb')
+      
+      # Camelize the string to get the class name
+      gateway_class = filename.camelize.to_sym
+            
+      # Register for autoloading
+      autoload gateway_class, f      
+    end
+
+    class CouldNotSubscribeToListException < Exception; end
+    class CouldNotUnsubscribeFromListException < Exception; end
+  end
+end

data/lib/active_esp/rfc822.rb

@@ -0,0 +1,34 @@
+# encoding: binary
+
+module ActiveESP #:nodoc:
+  # RFC822 Email Address Regex
+  # 
+  # Originally written by Cal Henderson
+  # c.f. http://iamcal.com/publish/articles/php/parsing_email/
+  #
+  # Translated to Ruby by Tim Fletcher, with changes suggested by Dan Kubb.
+  #
+  # Licensed under a Creative Commons Attribution-ShareAlike 2.5 License
+  # http://creativecommons.org/licenses/by-sa/2.5/
+  # 
+  # Source: http://tfletcher.com/lib/rfc822.rb
+  # RFC822: http://www.w3.org/Protocols/rfc822/#z8
+  module RFC822
+    EmailAddress = begin
+      qtext = '[^\\x0d\\x22\\x5c\\x80-\\xff]'
+      dtext = '[^\\x0d\\x5b-\\x5d\\x80-\\xff]'
+      atom = '[^\\x00-\\x20\\x22\\x28\\x29\\x2c\\x2e\\x3a-' +
+        '\\x3c\\x3e\\x40\\x5b-\\x5d\\x7f-\\xff]+'
+      quoted_pair = '\\x5c[\\x00-\\x7f]'
+      domain_literal = "\\x5b(?:#{dtext}|#{quoted_pair})*\\x5d"
+      quoted_string = "\\x22(?:#{qtext}|#{quoted_pair})*\\x22"
+      domain_ref = atom
+      sub_domain = "(?:#{domain_ref}|#{domain_literal})"
+      word = "(?:#{atom}|#{quoted_string})"
+      domain = "#{sub_domain}(?:\\x2e#{sub_domain})*"
+      local_part = "#{word}(?:\\x2e#{word})*"
+      addr_spec = "#{local_part}\\x40#{domain}"
+      pattern = /\A#{addr_spec}\z/
+    end
+  end
+end

data/lib/active_esp/subscriber.rb

@@ -0,0 +1,126 @@
+module ActiveESP
+  # A +Subscriber+ object represents an email address stored within a service provider's
+  # system.
+  #
+  # At the very least, an email address is required to have a valid subscriber.  If a name
+  # is also necessary, a +requires_name+ flag can be set on the class to indicate to the
+  # validator that it needs to check for a name as well.
+  #
+  # Email address are validated against the spec set forth in RFC822:
+  # http://www.w3.org/Protocols/rfc822/#z8
+  #
+  # == Example Usage
+  #   subscriber = ActiveESP::Subscriber.new(
+  #     :first_name => 'Billie Joe',
+  #     :last_name  => 'Armstong',
+  #     :email      => 'billie.joe@example.com'
+  #   )
+  #
+  #   subscriber.name   # => 'Billie Joe Armstrong'
+  #   subscriber.valid? # => true
+  #
+  class Subscriber
+    include RFC822
+
+    # Forces a first and last name to be present for the object to be valid.
+    # If true, the name is required.  The default value is false.
+    #
+    # @return [Boolean]
+    cattr_accessor :requires_name
+    self.requires_name = false
+
+    # Returns or sets the subscriber's ID as determined by the provider
+    #
+    # @return [String]
+    attr_accessor :id
+
+    # Returns or sets the subscriber's email address
+    #
+    # @return [String]
+    attr_accessor :email
+
+    # Returns or sets the subscriber's first name
+    #
+    # @return [String]
+    attr_accessor :first_name
+
+    # Returns or sets the subscriber's last name
+    #
+    # @return [String]
+    attr_accessor :last_name
+
+    # Initialize object with an optional attributes hash
+    #
+    # @param [Hash] attributes An optional hash of attributes to assign to the new instance
+    def initialize(attributes = nil)
+      if attributes.is_a? Hash
+        attributes.each do |key, value|
+          self.send(key.to_s + "=", value)
+        end
+      end
+    end
+
+    # Returns the full name of the subscriber.
+    #
+    # @return [String] the full name of the subscriber
+    def name
+      [@first_name, @last_name].compact.join(' ')
+    end
+
+    # Assigns first and last names based on specifiying a full name string
+    #
+    # @param [String] full_name The subscriber's full name to be split programatically
+    def name=(full_name)
+      names = full_name.split
+      self.last_name  = names.pop
+      self.first_name = names.join(" ")
+    end
+
+    # Returns whether either the +first_name+ or the +last_name+ attributes has been set.
+    def name?
+      first_name? || last_name?
+    end
+
+    # Returns whether the +first_name+ attribute has been set.
+    def first_name?
+      @first_name.present?
+    end
+
+    # Returns whether the +last_name+ attribute has been set.
+    def last_name?
+      @last_name.present?
+    end
+
+    def valid?
+      valid_email? && valid_name?
+    end
+
+    def valid_email?
+      @email =~ EmailAddress
+    end
+
+    def valid_name?
+      return false if self.class.requires_name && !name?
+      return true
+    end
+
+    # Accessing commonly used API calls
+
+    # Add the subscriber to the provider and optionally subscribe them to the
+    # given list.
+    #
+    # @see ActiveESP::Providers::Interface#subscribe
+    def subscribe!(list = nil)
+      raise ActiveESP::ProviderNotConfiguredException unless ActiveESP.provider
+      ActiveESP.provider.subscribe(self, list)
+    end
+
+    # Remove the subscriber from the given list.
+    #
+    # @see ActiveESP::Providers::Interface#unsubscribe
+    def unsubscribe!(list)
+      raise ActiveESP::ProviderNotConfiguredException unless ActiveESP.provider
+      ActiveESP.provider.unsubscribe(self, list)
+    end
+  end
+end

data/lib/active_esp/version.rb

@@ -0,0 +1,3 @@
+module ActiveESP
+  VERSION = "0.1.0.alpha1"
+end

data/lib/active_esp.rb

@@ -0,0 +1,28 @@
+require "interface"
+require "httparty"
+require "json"
+require "cgi"
+
+require "active_support/core_ext"
+require "active_support/inflector"
+require "active_esp/inflections"
+require "active_esp/version"
+require "active_esp/configuration"
+require "active_esp/rfc822"
+require "active_esp/subscriber"
+require "active_esp/list"
+
+# ActiveESP is an abstraction library for managing subscribers, campaigns, and other email
+# marketing facilities. It aims to provide a consistent interface to interact with the
+# numerous ESPs operating with different terminologies and strategies.
+#
+# This framework provides some common classes for managing email marketing data structures
+# as well as the adapters for interfacing with the providers' APIs.
+module ActiveESP
+  autoload :Providers, "active_esp/providers"
+  
+  include Configuration
+
+  class ProviderNotSupportedException < Exception; end
+  class ProviderNotConfiguredException < Exception; end
+end

data/spec/factories.rb

@@ -0,0 +1,7 @@
+FactoryGirl.define do
+  factory :subscriber, :class => ActiveESP::Subscriber do
+    first_name        "Billie Joe"
+    last_name         "Armstrong"
+    sequence(:email)  { |n| "kerplunk#{n}@example.com" }
+  end
+end

data/spec/models/subscriber_spec.rb

@@ -0,0 +1,142 @@
+require 'spec_helper'
+
+describe ActiveESP::Subscriber do
+  before(:each) do
+    ActiveESP::Subscriber.requires_name = false
+    @attributes = Factory.attributes_for(:subscriber)
+  end
+  
+  it "should properly assign attributes" do
+    subscriber = ActiveESP::Subscriber.new(@attributes)
+    subscriber.first_name.should eq(@attributes[:first_name])
+    subscriber.last_name.should eq(@attributes[:last_name])
+    subscriber.email.should eq(@attributes[:email])
+  end
+
+  it "should respond with the subscriber's full name" do
+    subscriber = ActiveESP::Subscriber.new(:first_name => 'Kris', :last_name => 'Roe')
+    subscriber.name.should eq('Kris Roe')
+  end
+
+  describe ".first_name?" do
+    it "should return true if a first name has been assigned" do
+      subscriber = ActiveESP::Subscriber.new(:first_name => 'Haushinka')
+      subscriber.first_name?.should be_true
+    end
+
+    it "should return false if a first name has not been assigned" do
+      subscriber = ActiveESP::Subscriber.new
+      subscriber.first_name?.should be_false
+    end
+
+    it "should return false if the first name is blank" do
+      subscriber = ActiveESP::Subscriber.new(:first_name => '')
+      subscriber.first_name?.should be_false
+    end
+  end
+
+  describe ".last_name?" do
+    it "should return true if a last name has been assigned" do
+      subscriber = ActiveESP::Subscriber.new(:last_name => 'Haushinka')
+      subscriber.last_name?.should be_true
+    end
+
+    it "should return false if a last name has not been assigned" do
+      subscriber = ActiveESP::Subscriber.new
+      subscriber.last_name?.should be_false
+    end
+
+    it "should return false if the last name is blank" do
+      subscriber = ActiveESP::Subscriber.new(:last_name => '')
+      subscriber.last_name?.should be_false
+    end
+  end
+
+  describe ".name?" do
+    it "should return true if a first name has been assigned" do
+      subscriber = ActiveESP::Subscriber.new(:first_name => 'Haushinka')
+      subscriber.name?.should be_true
+    end
+
+    it "should return true if a last name has been assigned" do
+      subscriber = ActiveESP::Subscriber.new(:last_name => 'Haushinka')
+      subscriber.name?.should be_true
+    end
+
+    it "should return false if neither a first name nor a last name has been assigned" do
+      subscriber = ActiveESP::Subscriber.new
+      subscriber.name?.should be_false
+    end
+  end
+
+
+  describe ".name=" do
+    it "should assign the last word of a given full name as the last name" do
+      subscriber = ActiveESP::Subscriber.new
+      subscriber.name = "Some Really Long Name Morton"
+      subscriber.last_name.should eq("Morton")
+    end
+
+    it "should assign the all words except the last of a given full name as the first name" do
+      subscriber = ActiveESP::Subscriber.new
+      subscriber.name = "Billie Joe Armstrong"
+      subscriber.first_name.should eq("Billie Joe")
+    end
+  end
+
+  describe ".valid_email?" do
+    it "should return true if the assigned email is valid" do
+      subscriber = ActiveESP::Subscriber.new(:email => 'user@example.com')
+      subscriber.should be_valid_email
+    end
+
+    it "should return false if the assigned email is not valid" do
+      subscriber = ActiveESP::Subscriber.new(:email => 'user')
+      subscriber.should_not be_valid_email
+    end
+  end
+
+  describe ".valid_name?" do
+    it "should return true if the name isn't required" do
+      ActiveESP::Subscriber.requires_name = false
+      subscriber = ActiveESP::Subscriber.new
+      subscriber.valid_name?.should be_true
+    end
+
+    it "should return true if the name is required and the name is present" do
+      ActiveESP::Subscriber.requires_name = true
+      subscriber = ActiveESP::Subscriber.new
+      subscriber.stub(:name?).and_return(true)
+      subscriber.valid_name?.should be_true
+    end
+
+    it "should return false if the name is required and the name isn't present" do
+      ActiveESP::Subscriber.requires_name = true
+      subscriber = ActiveESP::Subscriber.new
+      subscriber.stub(:name?).and_return(false)
+      subscriber.valid_name?.should_not be_true
+    end
+  end
+
+  describe ".valid?" do
+    it "should return true if the name and email address are valid" do
+      subscriber = ActiveESP::Subscriber.new
+      subscriber.stub(:valid_name?).and_return(true)
+      subscriber.stub(:valid_email?).and_return(true)
+      subscriber.valid?.should be_true
+    end
+
+    it "should return false if the name isn't valid" do
+      subscriber = ActiveESP::Subscriber.new
+      subscriber.stub(:valid_name?).and_return(false)
+      subscriber.valid?.should_not be_true
+    end
+
+    it "should return false if the email isn't valid" do
+      subscriber = ActiveESP::Subscriber.new
+      subscriber.stub(:valid_email?).and_return(false)
+      subscriber.valid?.should_not be_true
+    end
+  end
+
+end

data/spec/providers/icontact_spec.rb

@@ -0,0 +1,5 @@
+require 'spec_helper'
+
+describe ActiveESP::Providers::IContact do
+  it { should implement_interface(ActiveESP::Providers::Interface) }
+end

data/spec/providers/mail_chimp_spec.rb

@@ -0,0 +1,5 @@
+require 'spec_helper'
+
+describe ActiveESP::Providers::MailChimp do
+  it { should implement_interface(ActiveESP::Providers::Interface) }
+end

data/spec/spec_helper.rb

@@ -0,0 +1,11 @@
+require 'rubygems'
+require 'bundler/setup'
+require 'active_esp'
+require 'factory_girl'
+require './spec/factories'
+
+Dir[File.dirname(__FILE__) + "/support/**/*.rb"].each {|f| require f}
+
+RSpec.configure do |config|
+  # some (optional) config here
+end

data/spec/support/matchers/implement_interface.rb

@@ -0,0 +1,13 @@
+RSpec::Matchers.define :implement_interface do |expected|
+  match do |object|
+    @unimplemented_methods = object.unimplemented_methods.reject do |interface, methods|
+      interface != expected
+    end
+
+    @unimplemented_methods.empty?
+  end
+
+  failure_message_for_should do |actual|
+    "did not implement #{@unimplemented_methods.inspect}"
+  end
+end

metadata

@@ -0,0 +1,178 @@
+--- !ruby/object:Gem::Specification
+name: active_esp
+version: !ruby/object:Gem::Version
+  version: 0.1.0.alpha1
+  prerelease: 6
+platform: ruby
+authors:
+- Brian Morton
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-02-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: &70366026630040 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>'
+      - !ruby/object:Gem::Version
+        version: 1.4.0
+  type: :runtime
+  prerelease: false
+  version_requirements: *70366026630040
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: &70366026629440 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.1
+  type: :runtime
+  prerelease: false
+  version_requirements: *70366026629440
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: &70366026628960 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: *70366026628960
+- !ruby/object:Gem::Dependency
+  name: shuber-interface
+  requirement: &70366026628420 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.0.4
+  type: :runtime
+  prerelease: false
+  version_requirements: *70366026628420
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70366026627840 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.8.0
+  type: :development
+  prerelease: false
+  version_requirements: *70366026627840
+- !ruby/object:Gem::Dependency
+  name: factory_girl
+  requirement: &70366026627360 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.5.1
+  type: :development
+  prerelease: false
+  version_requirements: *70366026627360
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: &70366026626880 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.7.5
+  type: :development
+  prerelease: false
+  version_requirements: *70366026626880
+- !ruby/object:Gem::Dependency
+  name: thin
+  requirement: &70366026626380 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.3.1
+  type: :development
+  prerelease: false
+  version_requirements: *70366026626380
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: &70366026625920 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.1.0
+  type: :development
+  prerelease: false
+  version_requirements: *70366026625920
+description: Framework and tools for managing email service providers.
+email:
+- bmorton@sdreader.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- active_esp.gemspec
+- lib/active_esp.rb
+- lib/active_esp/configuration.rb
+- lib/active_esp/inflections.rb
+- lib/active_esp/list.rb
+- lib/active_esp/providers.rb
+- lib/active_esp/providers/base.rb
+- lib/active_esp/providers/icontact.rb
+- lib/active_esp/providers/interface.rb
+- lib/active_esp/providers/mail_chimp.rb
+- lib/active_esp/rfc822.rb
+- lib/active_esp/subscriber.rb
+- lib/active_esp/version.rb
+- spec/factories.rb
+- spec/models/subscriber_spec.rb
+- spec/providers/icontact_spec.rb
+- spec/providers/mail_chimp_spec.rb
+- spec/spec_helper.rb
+- spec/support/matchers/implement_interface.rb
+homepage: http://1703india.st/active_esp
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>'
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.16
+signing_key: 
+specification_version: 3
+summary: ActiveESP is an abstraction library for managing subscribers, campaigns,
+  and other email marketing facilities.  It provides a consistent interface to interact
+  with the numerous ESPs.
+test_files:
+- spec/factories.rb
+- spec/models/subscriber_spec.rb
+- spec/providers/icontact_spec.rb
+- spec/providers/mail_chimp_spec.rb
+- spec/spec_helper.rb
+- spec/support/matchers/implement_interface.rb
+has_rdoc: