acts_as_icontact 0.1.1

data/lib/acts_as_icontact/connection.rb

@@ -0,0 +1,32 @@
+module ActsAsIcontact
+  # Returns an instance of RestClient::Resource with iContact authentication headers. All other
+  # resource classes build from this method. Throws an ActsAsIcontact::ConfigError if the username
+  # or password are missing from configuration.
+  #
+  # (Author's Note: I'm not especially thrilled with this name, since it implies some sort of keepalive
+  # or other persistent state.  I'd rather call this 'client' -- but that's already a bit overloaded 
+  # within iContact's nomenclature.  And calling it 'server' got _me_ confused.  This is the best of a 
+  # motley array of possibilities.)
+  def self.connection
+    @connection or begin
+      raise ConfigError, "Username is required" unless Config.username
+      raise ConfigError, "Password is required" unless Config.password
+      @connection = RestClient::Resource.new(Config.url, :headers => {
+        :accept => Config.content_type,
+        :content_type => Config.content_type,
+        :api_version => Config.api_version,
+        :api_appid => Config.app_id,
+        :api_username => Config.username,
+        :api_password => Config.password
+      })
+    end
+  end
+  
+  # Clears the connection object from memory.  This will force a reload the next time it's accessed.
+  # Because nothing is directly cached within the client, the only likely reason to do this is if
+  # the username and password are changed.  Also resets the account subresource.
+  def self.reset_connection!
+    reset_account!
+    @connection = nil
+  end
+end

data/lib/acts_as_icontact/exceptions.rb

@@ -0,0 +1,19 @@
+module ActsAsIcontact
+  # Thrown when a configuration value isn't provided or is invalid.
+  class ConfigError < StandardError; end
+  
+  # Thrown when a resource calls save! and fails. Contains the +.errors+ array from
+  # the resource.
+  class RecordNotSaved < StandardError
+    attr_reader :errors
+    
+    def initialize(errors = [])
+      @errors = errors
+    end
+    
+    def message
+      errors.first
+    end
+    alias_method :error, :message
+  end
+end

data/lib/acts_as_icontact/resource.rb

@@ -0,0 +1,204 @@
+require 'activesupport'
+require 'uri'
+
+module ActsAsIcontact
+  # Base class for shared functionality between iContact resources.  Supports getting, finding, saving,
+  # all that fun stuff. 
+  class Resource
+    
+    # Creates a new resource object from a values hash.  (Which is passed to us via the magic of JSON.)
+    def initialize(properties={})
+      @properties = properties
+      @new_record = !@properties.has_key?(self.class.primary_key)
+      # Initialize other useful attributes
+      @errors = []
+      
+    end
+    
+    # Returns the primary key ID for an existing resource.  Returns nil if the resource is a new record.
+    def id
+      @properties[self.class.primary_key].to_i unless new_record?
+    end
+    
+    # Returns the specific RestClient connection for an existing resource.  (E.g., the connection
+    # to "http://api.icontact.com/icp/a/12345" for account 12345.)  Returns nil if the resource
+    # is a new record.
+    def connection
+      self.class.connection[id] unless new_record?
+    end
+    
+    # Enables keys from the iContact resource to act as attribute methods.
+    def method_missing(method, *params)
+      property = method.to_s
+      if property =~ /(.*)=$/  # It's a value assignment
+        @newvalues ||= []
+        @newvalues << $1
+        @properties[$1] = params[0]
+      else
+        if @properties.has_key?(property)
+          @properties[property]
+        else
+          super
+        end
+      end
+    end
+    
+    # Returns true if the resource object did not originate from iContact.  We determine this 
+    # by the rather naive method of checking upon creation whether one of the properties passed
+    # was the primary key.
+    def new_record?
+      @new_record
+    end
+    
+    # Sends changes to iContact.  Returns true if the save was successful (i.e. we receive
+    # an updated object back from them); if it was not, returns false and populates the
+    # +errors+ array with the warnings iContact sends to us.  If iContact returns an HTTP
+    # error, raises an exception with it.
+    def save
+      if new_record?
+        result_type = self.class.collection_name
+        payload = {self.class.collection_name => [create_fields]}
+        response = self.class.connection.post(payload.to_json)
+      else
+        result_type = self.class.resource_name
+        response = connection.post(update_fields.to_json)
+      end
+      parsed = JSON.parse(response)
+      if parsed[result_type].empty?
+        @errors = parsed["warnings"]
+        false
+      else
+        @properties = (new_record? ? parsed[result_type].first : parsed[result_type])
+        @new_record = false
+        @errors = []
+        true
+      end 
+    rescue RestClient::RequestFailed => e
+      response = e.response.body
+      parsed = JSON.parse(response)
+      @errors = parsed["errors"] || [e.message]
+      false
+    end
+    
+    # Like +save+, but raises an ActsAsIcontact::RecordNotSaved exception if the save
+    # failed.  The exception message contains the first error from iContact.
+    def save!
+      save or raise ActsAsIcontact::RecordNotSaved.new(errors)
+    end
+    
+    # The first message from the +errors+ array.
+    def error
+      errors.first
+    end
+    
+    # The warning messages sent back by iContact on a failed request.
+    def errors
+      @errors
+    end
+    
+    # Returns an array of resources starting at the base.
+    def self.find(type, options={})
+      uri_extension = uri_component + build_query(options)
+      response = base[uri_extension].get
+      parsed = JSON.parse(response)
+      case type
+      when :first then
+        self.new(parsed[collection_name].first) if parsed[collection_name]
+      when :all then
+        ResourceCollection.new(self, parsed)
+      end
+    end
+    
+    # Returns an array of resources starting at the base.
+    def self.all
+      find(:all)
+    end
+    
+    # Returns the first account associated with this username.
+    def self.first
+      find(:first)
+    end
+    
+    protected
+    # The minimum set of fields that must be sent back to iContact on an update.
+    # Includes any fields that changed or were added, the primary key, and anything
+    # else from the "required_on_update" set from the class definition.  It excludes
+    # anything from the "never_on_update" set.
+    def update_fields
+      fieldlist = self.class.required_on_update + @newvalues.to_a - self.class.never_on_update
+      @properties.select{|key, value| fieldlist.include?(key)}
+    end
+
+    # The minimum set of fields that must be sent back to iContact on a create.
+    # Includes any fields that were added and anything
+    # else from the "required_on_create" set from the class definition.  It excludes
+    # anything from the "never_on_create" set.
+    def create_fields
+      self.class.required_on_create.each{|key| @properties[key] ||= ""} # Add required fields
+      self.class.never_on_create.each{|key| @properties.delete(key)} # Remove prohibited fields
+      @properties
+    end
+    
+    # The base RestClient resource that this particular class nests from.  Starts with 
+    # the resource connection at 'https://api.icontact.com/icp/' and works its way up.
+    def self.base
+      ActsAsIcontact.connection
+    end
+    
+    # The name of the singular resource type pulled from iContact.  Defaults to the lowercase
+    # version of the class name.
+    def self.resource_name
+      name.demodulize.downcase
+    end
+
+    # The name of the resource collection pulled from iContact.  Defaults to the lowercase
+    # pluralized version of the class name.
+    def self.collection_name
+      resource_name.pluralize
+    end
+    
+    # The URI component name corresponding to this resource type.  In many cases it's the same as the
+    # collection name; exceptions include accounts ('a') and clientFolders ('c').
+    def self.uri_component
+      collection_name
+    end
+    
+    # The RestClient resource object for this resource class.  Its own find/update methods
+    # will call on this, and singular objects will derive from it.
+    def self.connection
+      base[uri_component]
+    end
+    
+    # The primary key field for this resource.  Used on updates.
+    def self.primary_key
+      resource_name + "Id"
+    end
+    
+    # Fields that _must_ be included for this resource upon creation.
+    def self.required_on_create
+      []
+    end
+    
+    # Fields that _must_ be included for this resource upon updating.
+    def self.required_on_update
+      [primary_key]
+    end
+    
+    # Fields that _cannot_ be included for this resource upon creation.
+    def self.never_on_create
+      [primary_key]
+    end
+    
+    # Fields that _cannot_ be included for this resource upon updating.
+    def self.never_on_update
+      []
+    end
+    
+    private
+    def self.build_query(options={})
+      return "" if options.empty?
+      terms = options.collect{|k,v| "#{k}=#{URI.escape(v.to_s)}"}
+      build = "?" + terms.join('&')
+    end
+  end
+end

data/lib/acts_as_icontact/resource_collection.rb

@@ -0,0 +1,27 @@
+module ActsAsIcontact
+  class ResourceCollection < Enumerator
+    attr_reader :total
+    
+    def initialize(klass, collection)
+      @klass = klass
+      @collection = collection[klass.collection_name]
+      # Get number of elements
+      @total = @collection.size
+      
+      enumcode = Proc.new do |yielder|
+        counter = 0
+        while counter < @total
+          yielder.yield klass.new(@collection[counter])
+          counter += 1
+        end
+      end
+              
+      super(&enumcode)
+    end
+    
+    def [](index)
+      @klass.new(@collection[index]) if @collection[index]
+    end
+    
+  end
+end

data/lib/acts_as_icontact/resources/account.rb

@@ -0,0 +1,38 @@
+module ActsAsIcontact
+  # The top-level Accounts resource from iContact.  Currently only supports retrieval -- and is 
+  # highly targeted toward the _first_ account, since that seems to be the dominant use case.
+  class Account < Resource
+    def self.uri_component
+      'a'
+    end
+    
+    # Accounts can't pass back a userName or password on updating
+    def self.never_on_update     
+      ['userName','password']
+    end
+  end
+  
+  # The accountId retrieved from iContact.  Can also be set manually for performance optimization,
+  # but remembers it so that it won't be pulled more than once anyway.
+  def self.account_id
+    @account_id ||= Account.first.accountId.to_i
+  end
+  
+  # Manually sets the accountId used in subsequent calls.  Setting this in your initializer will save
+  # at least one unnecessary request to the iContact server.
+  def self.account_id=(val)
+    @account_id = val
+  end
+  
+  # RestClient subresource scoped to the specific account ID.  Most other iContact calls will derive
+  # from this one.
+  def self.account
+    @account ||= connection["a/#{account_id}"]
+  end
+  
+  # Clears the account resource from memory.  Called by reset_connection! since the only likely reason
+  # to do this is connecting as a different user.
+  def self.reset_account!
+    @account = nil
+  end
+end

data/lib/acts_as_icontact/resources/client.rb

@@ -0,0 +1,45 @@
+module ActsAsIcontact
+  # The nested Client Folder resource from iContact.  Currently only supports retrieval -- and is 
+  # highly targeted toward the _first_ client folder, since that seems to be the dominant use case.
+  class Client < Resource
+    def self.resource_name
+      'clientfolder'
+    end
+    
+    def self.collection_name
+      'clientfolders'
+    end
+    
+    def self.uri_component
+      'c'
+    end
+    
+    def self.base
+      ActsAsIcontact.account
+    end
+  end
+  
+  # The clientFolderId retrieved from iContact.  Can also be set manually for performance 
+  # optimization, but remembers it so that it won't be pulled more than once anyway.
+  def self.client_id
+    @client_id ||= Client.first.clientFolderId.to_i
+  end
+  
+  # Manually sets the clientFolderId used in subsequent calls.  Setting this in your 
+  # initializer will save at least one unnecessary request to the iContact server.
+  def self.client_id=(val)
+    @client_id = val
+  end
+  
+  # RestClient subresource scoped to the specific account ID.  Most other iContact calls will derive
+  # from this one.
+  def self.client
+    @client ||= account["c/#{client_id}"]
+  end
+  
+  # Clears the account resource from memory.  Called by reset_connection! since the only likely reason
+  # to do this is connecting as a different user.
+  def self.reset_client!
+    @client = nil
+  end
+end

data/lib/acts_as_icontact/resources/contact.rb

@@ -0,0 +1,7 @@
+module ActsAsIcontact
+  class Contact < Resource
+    def self.required_on_create
+      ['email']
+    end
+  end
+end

data/spec/config_spec.rb

@@ -0,0 +1,181 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "Configuration" do
+  Rails = "dummy"
+  Rack = "dummy"
+  before(:all) do
+    # Copy our configuration to a safe place, then wipe it
+    @old_config = {}
+    ActsAsIcontact::Config.instance_variables.each do |v|
+      @old_config[v] = ActsAsIcontact::Config.instance_variable_get(v)
+      ActsAsIcontact::Config.instance_variable_set(v,nil)
+    end
+  end
+  
+  context "mode" do
+    before(:all) do
+      @old_mode = ENV["ICONTACT_MODE"]
+      ENV["ICONTACT_MODE"] = nil
+    end
+    it "defaults to production if nothing else is set" do
+      ActsAsIcontact::Config.mode.should == :production
+    end
+    
+    it "can set the mode attribute manually" do
+      ActsAsIcontact::Config.mode = :foo
+      ActsAsIcontact::Config.mode.should == :foo
+    end
+
+    it "reads the ICONTACT_MODE environment variable" do
+      ENV["ICONTACT_MODE"] = 'bar'
+      ActsAsIcontact::Config.mode.should == :bar
+      ENV["ICONTACT_MODE"] = @old_mode 
+    end
+      
+    context "within a Rails application" do
+      before(:all) do
+        @old_rails_env = ENV["RAILS_ENV"]
+      end
+      
+      before(:each) do
+        Object.expects(:const_defined?).with(:Rails).returns(true)
+      end
+      
+      it "is beta if RAILS_ENV is not production" do
+        ENV["RAILS_ENV"] = 'staging'
+        ActsAsIcontact::Config.mode.should == :beta
+      end
+      
+      it "is production if RAILS_ENV is production" do
+        ENV["RAILS_ENV"] = 'production'
+        ActsAsIcontact::Config.mode.should == :production
+      end
+      
+      after(:all) do
+        ENV["RAILS_ENV"] = @old_rails_env 
+      end
+    end
+
+    context "within a Rack environment" do
+      before(:all) do
+        @old_rack_env = ENV["RACK_ENV"]
+      end
+      before(:each) do
+        Object.expects(:const_defined?).with(:Rails).returns(false)
+        Object.expects(:const_defined?).with(:Rack).returns(true)
+      end
+      
+      it "is beta if RACK_ENV is not production" do
+        ENV["RACK_ENV"] = 'staging'
+        ActsAsIcontact::Config.mode.should == :beta
+      end
+      
+      it "is production if RACK_ENV is production" do
+        ENV["RACK_ENV"] = 'production'
+        ActsAsIcontact::Config.mode.should == :production
+      end
+      
+      after(:all) do
+        ENV["RACK_ENV"] = @old_rack_env
+      end
+    end
+
+    
+    context ":beta" do
+      before(:each) do
+        ActsAsIcontact::Config.mode = :beta        
+      end
+      
+      it "returns the beta AppId" do
+        ActsAsIcontact::Config.app_id.should == "Ml5SnuFhnoOsuZeTOuZQnLUHTbzeUyhx"
+      end
+    
+      it "returns the beta URL" do
+        ActsAsIcontact::Config.url.should == "https://app.beta.icontact.com/icp/"
+      end
+      
+    end
+  
+    context ":production" do
+      before(:each) do
+        ActsAsIcontact::Config.mode = :production        
+      end
+          
+      it "returns the production AppId" do
+        ActsAsIcontact::Config.app_id.should == "IYDOhgaZGUKNjih3hl1ItLln7zpAtWN2"
+      end
+    
+      it "returns the production URL" do
+        ActsAsIcontact::Config.url.should == "https://app.icontact.com/icp/"
+      end
+      
+    end
+
+    after(:each) do
+      ActsAsIcontact::Config.mode = nil
+      ENV["ICONTACT_MODE"] = nil
+    end
+    
+    after(:all) do
+      ENV["ICONTACT_MODE"] = @old_mode
+    end
+    
+  end
+  
+  it "knows it's version 2.0" do
+    ActsAsIcontact::Config.api_version.should == 2.0
+  end
+  
+  it "can set its URL base" do
+    ActsAsIcontact::Config.url = "https://blah.example.com/foo/bar/"
+    ActsAsIcontact::Config.url.should == "https://blah.example.com/foo/bar/"
+  end
+  
+  it "knows its content type" do
+    ActsAsIcontact::Config.content_type.should == "application/json"
+  end
+  
+  it "can set its content type to XML" do
+    ActsAsIcontact::Config.content_type = "text/xml"
+    ActsAsIcontact::Config.content_type.should == "text/xml"
+  end
+  
+  it "throws an error if the content type is anything other than JSON or XML" do
+    lambda{ActsAsIcontact::Config.content_type = "text/plain"}.should raise_error(ActsAsIcontact::ConfigError, "Content Type must be application/json or text/xml")
+  end
+  
+  it "knows the username you give it" do
+    ActsAsIcontact::Config.username = "johndoe"
+    ActsAsIcontact::Config.username.should == "johndoe"
+  end
+  
+  it "gets the username from an environment variable if not supplied" do
+    old_env = ENV['ICONTACT_USERNAME']
+    ENV['ICONTACT_USERNAME'] = "bobdoe"
+    ActsAsIcontact::Config.username.should == "bobdoe"
+    # Set our environment back to the way we like it
+    ENV['ICONTACT_USERNAME'] = old_env if old_env
+  end
+
+  it "knows the password you give it" do
+    ActsAsIcontact::Config.password = "foobar"
+    ActsAsIcontact::Config.password.should == "foobar"
+  end
+  
+  it "gets the username from an environment variable if not supplied" do
+    old_env = ENV['ICONTACT_PASSWORD']
+    ENV['ICONTACT_PASSWORD'] = "hoohar"
+    ActsAsIcontact::Config.password.should == "hoohar"
+    ENV['ICONTACT_PASSWORD'] = old_env if old_env
+  end
+  
+  after(:each) do
+    # Clear any variables we might have set
+    ActsAsIcontact::Config.instance_variables.each{|v| ActsAsIcontact::Config.instance_variable_set(v,nil)}
+  end
+  
+  after(:all) do
+    # Restore our saved configuration
+    @old_config.each_pair {|k, v| ActsAsIcontact::Config.instance_variable_set(k,v)}
+  end
+end