acts_as_icontact 0.1.1

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,6 @@
+*.sw?
+*.tmproj
+.DS_Store
+coverage
+rdoc
+pkg

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Stephen Eley
+
+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.markdown

@@ -0,0 +1,196 @@
+ActsAsIcontact
+==============
+ActsAsIcontact connects Ruby applications with the [iContact e-mail marketing service](http://icontact.com) using the iContact API v2.0.  Building on the [RestClient](http://rest-client.heroku.com) gem, it offers two significant feature sets:
+
+* Simple, consistent access to all resources in the iContact API; and
+* Automatic synchronizing between ActiveRecord models and iContact contact lists for Rails applications.
+
+Prerequisites
+-------------
+You'll need the following to use this gem properly:
+
+1. **Ruby 1.9** Yeah, we know, change is _scary_ and a zillion of your other gems only work in 1.8. But ActsAsIcontact makes use of a few 1.9 features for efficiency, such as Enumerators.  It's _possible_ that this might work in 1.8.7 if you install the **JSON** gem and `require 'enumerator'` explicitly -- but the author hasn't tested it.  If you need it to work in 1.8, speak up.  Or better yet, make it work and submit a patch.
+
+2. **Rails 2.1** _(If using Rails integration)_ We use ActiveRecord's 'dirty fields' feature that first appeared in 2.1 to determine whether iContact needs updating.  If you're on a version of Rails older than this, it's probably worth your while to update anyway.
+
+3. **rest-client** This gem _should_ install when you install the **acts\_as\_icontact** gem.  But we include it here for completeness.
+
+Setting Up
+----------
+Using ActsAsIcontact is easy, but going through iContact's authorization process requires jumping a couple of hoops.  Here's how to get going quickly:
+
+1. Install the gem.
+
+       $ sudo gem install acts_as_icontact
+
+2. _Optional but recommended:_ Go to <http://beta.icontact.com> and sign up for an iContact Beta account. This will let you test your app without risk of blowing away your production mailing lists.
+
+3. Enable the ActsAsIcontact gem for use with your iContact account. The URL and credentials you'll use are different between the beta and production environments:  
+  
+     * **BETA:** Go to <http://app.beta.icontact.com/icp/core/externallogin> and enter `Ml5SnuFhnoOsuZeTOuZQnLUHTbzeUyhx` for the Application Id. Choose a password for ActsAsIcontact that's different from your account password.  
+  
+     * **PRODUCTION:** Go to <http://app.icontact.com/icp/core/externallogin> and enter `IYDOhgaZGUKNjih3hl1ItLln7zpAtWN2` for the Application Id. Choose a password for ActsAsIcontact that's different from your account password.
+  
+4. Set your _(beta, if applicable)_ account username and the password you just chose for API access. You can either set the environment variables `ICONTACT_MODE`, `ICONTACT_USERNAME`, and `ICONTACT_PASSWORD`, or you can explicitly do it with calls to the Config module:  
+
+        require 'rubygems'
+        require 'acts_as_icontact'
+    
+        ActsAsIcontact::Config.mode = :beta
+        ActsAsIcontact::Config.username = my_beta_username
+        ActsAsIcontact::Config.password = my_api_password  
+  
+    If you're using Rails, the recommended approach is to require the gem with `config.gem 'acts_as_icontact'` in your **config/environment.rb** file, and then set up an initializer (i.e. **config/initializers/acts\_as\_icontact.rb**) with the above code.  See more about Rails below.
+
+5. Rinse and repeat with production credentials when you're ready to move out of the beta environment.  
+
+API Access
+----------
+Whether or not you're using Rails, retrieving and modifying iContact resources is simple.  The gem autodiscovers your account and client folder IDs (you only have one of each unless you're an 'agency' account), so you can jump straight to the good parts:
+
+     contacts = ActsAsIcontact::Contact.find(:all)  # => <#ActsAsIcontact::ResourceCollection>
+     c = contacts.first    # => <#ActsAsIcontact.Contact>
+     c.firstName           # => "Bob"
+     c.lastName            # => "Smith"
+     c.email               # => "bob@example.org"
+     c.lastName = "Smith-Jones"   # Bob gets married and changes his name
+     c.save                # => true
+     history = c.actions   # => <#ActsAsIcontact::ResourceCollection>
+     a = history.first     # => <#ActsAsIcontact::Action>
+     a.actionType          # => "EditFields"
+  
+  
+### Nesting
+The interface is deliberately as "ActiveRecord-like" as possible, with methods linking resources that are either nested in iContact's URLs or logically related.  Messages have a Message#bounces method.  Lists have List#subscribers to list the Contacts subscribed to them, and Contacts have Contact#lists.  Read the documentation for each class to find out what you can do:
+
+* ActsAsIcontact::Account
+  * ActsAsIcontact::ClientFolder
+* ActsAsIcontact::Contact
+  * ActsAsIcontact::History _(documented as "Contact History")_
+* ActsAsIcontact::Message
+  * ActsAsIcontact::Bounce
+  * ActsAsIcontact::Click
+  * ActsAsIcontact::Open
+  * ActsAsIcontact::Unsubscribe
+  * ActsAsIcontact::Statistics
+* ActsAsIcontact::List
+  * ActsAsIcontact::Segment
+      * ActsAsIcontact::Criterion  _(documented as "Segment Criteria")_
+* ActsAsIcontact::Subscription
+* ActsAsIcontact::Campaign
+* ActsAsIcontact::CustomField
+* ActsAsIcontact::Send
+* ActsAsIcontact::Upload
+* ActsAsIcontact::User
+  * ActsAsIcontact::Permission
+* ActsAsIcontact::Time
+
+### Searching
+Searches are handled in a sane way using the same query options that iContact accepts.  The following are all valid:
+
+`Messages.all` -- *Same as `Messages.find(:all)`*  
+`Messages.first` -- *Same as `Messages.find(:first)`*  
+`Messages.find(:all, :limit => 20)` -- *First 20 messages*  
+`Messages.find(:all, :limit => 20, :offset => 40)` -- *Messages 41-60*  
+`Messages.first(:subject => "Fnord")` -- *First message with the given subject*  
+`Messages.all(:orderby => createDate, :desc => true)` -- *Messages ordered by most recent first*  
+`Messages.all(:messageType => "welcome", :campaignId => 11)` -- *Welcome messages from the given campaign*  
+
+At this time, special searches are not yet supported.  Fields requiring dates must also be given a string corresponding to the ISO8601 timestamp (e.g. `2006-09-16T14:30:00-06:00`).  Proper date/time conversion will happen soon.
+
+### Updating
+
+Again, think ActiveRecord.  When you initialize an object, you can optionally pass it a hash of values:
+
+    c = Contact.new(:firstName => "Bob", 
+                    :lastName => "Smith-Jones", 
+                    :email => "bob@example.org")
+    c.address = "123 Test Street"
+
+Each resource class has a `#save` method which returns true or false.  If false, the `#error` method contains the reply back from iContact about what went wrong.  (Which may or may not be informative, but we can't tell you more than they do.)  There's also a`#save!`method which throws an exception instead.
+
+Nested resources can be created using the `build_` method (which returns an object but doesn't save it right away) or `create_` method (which does save it upon creation).  The full panoply of ActiveRecord association methods are not implemented yet.  (Hey, we said it was AR-_like._)
+
+The `#delete` method on each class works as you'd expect, assuming iContact allows deletes on that resource.  Resource collections containing the resource are not updated, however, so you may need to requery.
+
+Multiple-record updates are not implemented at this time.
+
+Rails Integration
+-----------------
+The _real_ power of ActsAsIcontact is its automatic syncing with ActiveRecord.  At this time this feature is focused entirely on Contacts.  
+
+### Activation
+First add the line `config.gem 'acts_as_icontact'` to your **config/environment.rb** file.  Then create an initializer (e.g. **config/initializers/acts\_as\_icontact.rb**) and set it up with your username and password.  If applicable, you can give it both the beta _and_ production credentials:
+
+    module ActsAsIcontact
+      case Config.mode
+			when :beta
+        Config.username = my_beta_username
+        Config.password = my_beta_password
+      when :production
+        Config.username = my_production_username
+        Config.password = my_production_password
+      end
+    end
+
+If ActsAsIcontact detects that it's running in a Rails app, the default behavior is to set the mode to `:production` if RAILS\_ENV is equal to "production" and `:beta` if RAILS\_ENV is set to anything else.  (Incidentally, if you're _not_ in a Rails app but running Rack, the same logic applies for the RACK\_ENV environment variable.)
+
+Finally, enable one of your models to synchronize with iContact with a simple declaration:
+
+    class Person < ActiveRecord::Base
+      acts_as_icontact
+    end
+  
+There are some options, of course; we'll get to those in a bit.
+
+### What Happens
+When you call the `acts_as_icontact` method in an ActiveRecord class declaration, the gem does several useful things:
+
+1. Creates callbacks to post changes to iContact's API after a record is saved or deleted.
+2. Defines an `icontact_sync!` method to pull the contact's data _from_ iContact and make any changes.
+3. Defines other methods such as `icontact_lists` and `icontact_history` to make related data accessible.
+4. If an `icontact_status` field exists, creates named scopes on the model class for each iContact status.  _(Pending)_
+
+### Options
+Option values and field mappings can be passed to the `acts_as_icontact` declaration to set default behavior for the model class.  Right now there's only one option:
+
+`default_lists` -- _The name or ID number of a list to subscribe new contacts to automatically, or an array of said names or numbers_
+
+### Field Mappings
+You can add contact integration to any ActiveRecord model that tracks an email address.  (If your model _doesn't_ include email but you want to use iContact with it, you are very, very confused.)
+
+Any fields that are named the same as iContact's personal information fields, or custom fields you've previously declared, will be autodiscovered.  Otherwise you can map them:
+
+    class Customer < ActiveRecord::Base
+      acts_as_icontact :default_lists => ['New Customers', 'All Users']  # Puts new contact on two lists
+                       :given_name => :firstName, # Key is Rails field, value is iContact field
+                       :family_name => :lastName,
+                       :address1 => :street,
+                       :address2 => :street2,
+                       :id => :rails_id, # Custom field created in iContact
+                       :preferred? => :preferred_customer # Custom field
+    end
+
+A few iContact-specific fields are exceptions, and have different autodiscovery names to avoid collisions with other attributes in your application:
+
+`icontact_id` -- _Corresponds to `contactId` in iContact.  Highly recommended._  
+`icontact_status` -- _Corresponds to `status` in iContact._  
+`icontact_created` -- _Corresponds to `createDate` in iContact._
+`icontact_bounces` -- _Corresponds to `bounceCount` in iContact._
+
+You are welcome to create these fields in your model or omit them.  However, we _strongly_ recommend that you either include the `icontact_id` field to track iContact's primary key in your application, or map your own model's primary key to a custom field in iContact.  You can also do both for two-way associations.  If you don't establish a relationship with at least one ID, ActsAsIcontact will resort to using the email address for lookups -- which will be a problem if the email address changes.
+
+### Lists
+The reason to add contacts to iContact is to put them on mailing lists.  We know this.  The `default_list` option (see above) is one way to do it automatically.  The following methods are also defined on the model for your convenience:
+
+`icontact_lists` -- _An array of List objects to which the contact is currently subscribed_
+`icontact_subscribe(list)` -- _Given a list name or ID number, subscribes the contact to that list immediately_
+`icontact_unsubscribe(list)` -- _Given a list name or ID number, unsubscribes the contact from that list_
+
+
+### Why Just Contacts?
+iContact's interface is really quite good at handling pretty much every other resource.  Campaigns, segments, etc. can usually stand alone.  It's less likely that you'll need to keep copies of them in your Rails app.  But contacts are highly entangled.  If you're using iContact to communicate with your app's users or subjects, you'll want to keep iContact up-to-date when they change.  And if someone bounces or unsubscribes in iContact, odds are good you'll want to know about it.  So this is the strongest point of coupling and the highest priority feature.  (Lists will likely come next, followed by messages.)
+
+Copyright
+---------
+Copyright (c) 2009 Stephen Eley. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,57 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "acts_as_icontact"
+    gem.summary = "Automatic bridge between iContact e-mail marketing service and Rails ActiveRecord"
+    gem.email = "sfeley@gmail.com"
+    gem.homepage = "http://github.com/SFEley/acts_as_icontact"
+    gem.authors = ["Stephen Eley"]
+    gem.rubyforge_project = "actsasicontact"
+    gem.extra_rdoc_files = ["README.markdown"]
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+    gem.description = <<ENDDESC
+ActsAsIcontact connects Ruby applications with the iContact e-mail marketing service using the iContact API v2.0.  Building on the RestClient gem, it offers two significant feature sets:
+
+* Simple, consistent access to all resources in the iContact API; and
+* Automatic synchronizing between ActiveRecord models and iContact contact lists for Rails applications.
+ENDDESC
+  end
+
+  Jeweler::RubyforgeTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+
+task :default => :spec
+
+require 'hanna/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "acts_as_icontact #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+

data/VERSION

@@ -0,0 +1 @@
+0.1.1

data/acts_as_icontact.gemspec

@@ -0,0 +1,74 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{acts_as_icontact}
+  s.version = "0.1.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Stephen Eley"]
+  s.date = %q{2009-07-24}
+  s.description = %q{ActsAsIcontact connects Ruby applications with the iContact e-mail marketing service using the iContact API v2.0.  Building on the RestClient gem, it offers two significant feature sets:
+
+* Simple, consistent access to all resources in the iContact API; and
+* Automatic synchronizing between ActiveRecord models and iContact contact lists for Rails applications.
+}
+  s.email = %q{sfeley@gmail.com}
+  s.extra_rdoc_files = [
+    "README.markdown"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.markdown",
+     "Rakefile",
+     "VERSION",
+     "acts_as_icontact.gemspec",
+     "lib/acts_as_icontact.rb",
+     "lib/acts_as_icontact/config.rb",
+     "lib/acts_as_icontact/connection.rb",
+     "lib/acts_as_icontact/exceptions.rb",
+     "lib/acts_as_icontact/resource.rb",
+     "lib/acts_as_icontact/resource_collection.rb",
+     "lib/acts_as_icontact/resources/account.rb",
+     "lib/acts_as_icontact/resources/client.rb",
+     "lib/acts_as_icontact/resources/contact.rb",
+     "spec/config_spec.rb",
+     "spec/connection_spec.rb",
+     "spec/resource_collection_spec.rb",
+     "spec/resource_spec.rb",
+     "spec/resources/account_spec.rb",
+     "spec/resources/client_spec.rb",
+     "spec/resources/contact_spec.rb",
+     "spec/spec.opts",
+     "spec/spec_fakeweb.rb",
+     "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/SFEley/acts_as_icontact}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{actsasicontact}
+  s.rubygems_version = %q{1.3.4}
+  s.summary = %q{Automatic bridge between iContact e-mail marketing service and Rails ActiveRecord}
+  s.test_files = [
+    "spec/config_spec.rb",
+     "spec/connection_spec.rb",
+     "spec/resource_collection_spec.rb",
+     "spec/resource_spec.rb",
+     "spec/resources/account_spec.rb",
+     "spec/resources/client_spec.rb",
+     "spec/resources/contact_spec.rb",
+     "spec/spec_fakeweb.rb",
+     "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end

data/lib/acts_as_icontact.rb

@@ -0,0 +1,19 @@
+require 'rubygems'
+require 'rest_client'
+require 'json'
+
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'acts_as_icontact/exceptions'
+require 'acts_as_icontact/config'
+require 'acts_as_icontact/connection'
+require 'acts_as_icontact/resource'
+require 'acts_as_icontact/resource_collection'
+
+# Load all of our resource files
+Dir[File.join(File.dirname(__FILE__), 'acts_as_icontact', 'resources', '*.rb')].sort.each do |path|
+  filename = File.basename(path, '.rb')
+  require "acts_as_icontact/resources/#{filename}"
+end
+
+module ActsAsIcontact
+end

data/lib/acts_as_icontact/config.rb

@@ -0,0 +1,106 @@
+module ActsAsIcontact
+  # Predefined and user-supplied parameters for interfacing with iContact. Most of these are
+  # required by the iContact API for authentication.
+  module Config
+    
+    # Sets :production or :beta.  This changes the AppId and URL.
+    def self.mode=(val)
+      @mode = val
+    end
+    
+    # Determines whether to return the beta or production AppId and URL.  
+    # If not explicitly set, it will first look for an ICONTACT_MODE environment variable.
+    # If it doesn't find one, it will attempt to detect a Rails or Rack environment; in either
+    # case it will default to :production if RAILS_ENV or RACK_ENV is 'production', and :beta
+    # otherwise.  If none of these conditions apply, it assumes :production.  (Because that
+    # probably means someone's doing ad hoc queries.)
+    def self.mode
+      @mode ||= case
+      when ENV["ICONTACT_MODE"] 
+        ENV["ICONTACT_MODE"].to_sym
+      when Object.const_defined?(:Rails)
+        (ENV["RAILS_ENV"] == 'production' ? :production : :beta)
+      when Object.const_defined?(:Rack)
+        (ENV["RACK_ENV"] == 'production' ? :production : :beta)
+      else
+        :production
+      end
+    end
+    
+    
+    # Passed in the header of every request as the *API-AppId:* parameter. You should not need
+    # to change this.  Ever.
+    def self.app_id
+      case mode
+      when :beta
+        "Ml5SnuFhnoOsuZeTOuZQnLUHTbzeUyhx" 
+      when :production
+        "IYDOhgaZGUKNjih3hl1ItLln7zpAtWN2"
+      end
+    end
+    
+    # The API version that this code is designed to interface with.
+    def self.api_version
+      2.0
+    end
+    
+    # Prefixed to the beginning of every API request.  You can override this if you have some special 
+    # need (e.g. working against a testing server, or if iContact takes their API out of beta and 
+    # changes the URI before the gem gets updated), but for the most part you can leave it alone.
+    def self.url
+      @url ||= case mode
+      when :beta
+        "https://app.beta.icontact.com/icp/"
+      when :production
+        "https://app.icontact.com/icp/"
+      end
+    end
+    
+    # Overrides the base URL for the API request.  
+    def self.url=(val)
+      @url = val
+    end
+    
+    # Used in the "Accept:" and "Content-Type:" headers of every API request.  Defaults to JSON, and
+    # if you're simply using the gem methods there's no reason you should ever change this, as the
+    # results are auto-parsed into Ruby structures.  But you can set it to text/xml if you want to.
+    def self.content_type
+      @content_type ||= "application/json"
+    end
+    
+    # If you change this to anything other than application/json or text/xml you'll get an error.
+    # So sayeth iContact; so say we all.
+    def self.content_type=(val)
+      case val
+      when "text/xml"
+        @content_type = val
+      when "application/json"
+        @content_type = val
+      else
+        raise ActsAsIcontact::ConfigError, "Content Type must be application/json or text/xml"
+      end
+    end
+    
+    # Required for every API request.  If you're using these methods in a Rails app, the recommended
+    # way to set the username is in a Rails initializer file.  You can also set the ICONTACT_USERNAME
+    # environment variable.
+    def self.username
+      @username ||= ENV['ICONTACT_USERNAME']
+    end
+    
+    def self.username=(val)
+      @username = val
+    end
+
+    # Required for every API request.  If you're using these methods in a Rails app, the recommended
+    # way to set the password is in a Rails initializer file.  You can also set the ICONTACT_PASSWORD
+    # environment variable.
+    def self.password
+      @password ||= ENV['ICONTACT_PASSWORD']
+    end
+    
+    def self.password=(val)
+      @password = val
+    end
+  end
+end