acts_as_icontact 0.3.0 → 0.3.2

data/README.markdown

@@ -1,19 +1,20 @@
 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:
+ActsAsIcontact connects Ruby applications with the [iContact e-mail marketing service][1] using the iContact API v2.0.  Building on the [RestClient][2] gem, it offers three significant feature sets:
 
-* Simple, consistent access to all resources in the iContact API; and
+* Simple, consistent access to all resources in the iContact API; 
+* A simple command-line client; 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.
+1. **Ruby 1.9:** Yes, we know, many other gems still only work in 1.8. But ActsAsIcontact makes use of a few 1.9.1 features for efficiency, such as fiber-based Enumerators to step through large collections without instantiating a thousand objects at once.  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.
+2. **Rails 2.1 or higher:** _(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.
+3. **Other gems:** This gem requires the [RestClient][2], [ActiveSupport][3] and [Bond][4] gems in order to work.  Simply doing a `gem install` _should_ install these dependencies as well.
 
 Setting Up
 ----------
@@ -31,21 +32,36 @@ Using ActsAsIcontact is easy, but going through iContact's authorization process
   
      * **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 _(sandbox, 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:  
+4. Set your _(sandbox, if applicable)_ account username and the password you just chose for API access. See the next section for how to specify these.
+
+5. Rinse and repeat with production credentials when you're ready to move out of the sandbox environment.  For more information, consult the [iContact API developer documentation][5].
+
+Authentication
+--------------
+ActsAsIcontact already knows iContact's URL and its own Application Id, so the only things you need to tell it are your username, password, and whether you want to access the production or sandbox environments.  There are three simple ways to do that:
+
+1. Set the environment variables `ICONTACT_MODE`, `ICONTACT_USERNAME`, and `ICONTACT_PASSWORD`.  The `ICONTACT_MODE` environment variable should have a value of either ___production___ or ___sandbox___.
+
+2. Create a directory called **.icontact** under your home directory and place a YAML file in it titled **config.yml**:
+        ---
+        mode: production
+        username: my_username
+        password: my_password
+    This hidden directory is also used for the command line client's history file, and future versions of ActsAsIcontact may use it for caching.
+    
+3. You can explicitly set them anywhere in your code with calls to the Config module (note that the mode is a symbol, not a string):  
 
         require 'rubygems'
         require 'acts_as_icontact'
     
         ActsAsIcontact::Config.mode = :sandbox
-        ActsAsIcontact::Config.username = my_sandbox_username
-        ActsAsIcontact::Config.password = my_api_password  
+        ActsAsIcontact::Config.username = "my_sandbox_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 sandbox environment.  
-
-API Access
-----------
+Using the API
+-------------
 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>
@@ -61,7 +77,7 @@ Whether or not you're using Rails, retrieving and modifying iContact resources i
   
   
 ### 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:
+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][5] for each class to find out what you can do:
 
 * ActsAsIcontact::Account
   * ActsAsIcontact::ClientFolder
@@ -86,17 +102,64 @@ The interface is deliberately as "ActiveRecord-like" as possible, with methods l
 * ActsAsIcontact::Time
 
 ### Searching
-Searches are handled in a sane way using the same query options that iContact accepts.  The following are all valid:
+Searches are handled using the same query options that iContact accepts, but with a syntax based on ActiveRecord.  At this time, special searches (i.e. _gte_, _bet_ etc.) are not yet supported.  Fields requiring dates must 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.  See the [iContact developer docs][5] for available search options.
+
+The following class methods are offered (using the Message class as an example):
+
+#### Message.first
+
+Returns a single Message.  With no parameters, it returns the first Message in iContact's system, which may be arbitrary.  You can specify one or more search parameters as an options hash (note the Ruby 1.9 syntax):
+    Message.first(messageType: "welcome")  # => The first welcome message
+    Message.first(orderby: "createDate:desc")  # => Most recent message
+    
+If no records can be found matching the parameters, the **first** method returns nil.
+    
+#### Message.all
+
+Returns a collection of Messages matching the search parameters.  The _limit_ and _offset_ parameters are important here; if no _limit_ is provided, a default limit of 500 records is used.  (That default is also the maximum, at the request of iContact's technical staff.)
+
+The collection is an object of type ResourceCollection, and it acts both as an array and an enumerator.  For efficiency, individual Message objects are instantiated only when you access them.  
+    Message.all(messageType: "confirmation")  # => All confirmation messages (up to 500)
+    Message.all(limit: 20)  # => The first 20 messages
+    Message.all(limit: 20, offset: 40)  # => Messages 41-60
+    Message.all(offset:500)  # => Messages 501-1000
+    
+    # Example of collection iteration
+    @messages = Message.all  # => Assigns the first 500 messages to @messages
+    @messages.count  # => Number of messages
+    @messages[11]    # => Twelfth message in the collection (arrays are 0-based)
+    @messages.first  # => First message
+    @messages.next   # => Second message
+    @messages.next   # => Third message (et cetera)
+    
+If no records can be found matching the parameters, the **all** method returns nil.
+
+#### Message.find
 
-`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*  
+Like its ActiveRecord role model, #find has several behaviors depending on its parameter list:
+
+    Message.find(:first, messageType: "welcome")  # => Identical to Message.first(messageType: "welcome")
+    Message.find(:all, limit: 20)  # => Identical to Message.all(limit: 20)
+    Message.find(7)  # => Single Message found with messageId of 7
+    Message.find("foo")  # => Single Message found with subject of "foo"
+
+The _integer_ and _string_ parameter modes warrant some explanation.  Passing an integer to **find** on most resource classes will do a primary key lookup.  So Accounts will match on the accountId, Contacts will match on the contactId, etc.  The integer variant is unsupported for the CustomField and Subscription classes, which use string-based primary keys.
+
+Passing a string to **find** on most resource classes will do a single-record search based on the field most likely to be unique and important:
+
+* **Account:** userName
+* **Campaign:** name
+* **ClientFolder:** name
+* **Contact:** email
+* **CustomField:** customFieldId _(primary key)_
+* **List:** name
+* **Message:** subject
+* **Segment:** name
+* **Subscription:** subscriptionId _(primary key)_
+* **User:** userName
+
+If no records can be found using **find**, the _:first_ and _:all_ variants will return nil (just like **first** and **all**).  The _integer_ and _string_ variants will return an exception, on the assumption that you knew exactly what you were looking for and expected it to be there.  (I.e., matching the behavior of ActiveRecord.)
 
-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
 
@@ -107,11 +170,11 @@ Again, think ActiveRecord.  When you initialize an object, you can optionally pa
                     :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.
+Each resource object 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 on failure instead of returning false.
 
-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._)
+Nested resources can be created using the **build\_foo** method (which returns an object but doesn't save it right away) or **create\_foo** 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.
+The **#delete** method on each object 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.
 
@@ -197,4 +260,10 @@ iContact's interface is really quite good at handling pretty much every other re
 
 Copyright
 ---------
-Copyright (c) 2009 Stephen Eley. See LICENSE for details.
+Copyright (c) 2009 Stephen Eley. See LICENSE for details.
+
+[1]: http://icontact.com "iContact"
+[2]: http://rest-client.heroku.com "Rest-Client"
+[3]: http://as.rubyonrails.org/ "ActiveSupport"
+[4]: http://tagaholic.me/bond "Bond"
+[5]: http://developer.icontact.com/ "iContact Developer Portal"

data/Rakefile

@@ -10,7 +10,18 @@ begin
     gem.homepage = "http://github.com/SFEley/acts_as_icontact"
     gem.authors = ["Stephen Eley"]
     gem.rubyforge_project = "actsasicontact"
+    gem.executables = "icontact"
+    gem.has_rdoc = true
     gem.extra_rdoc_files = ["README.markdown"]
+    gem.rdoc_options << '--all'
+    gem.add_dependency 'rest-client', '>= 1.0'
+    gem.add_dependency 'activesupport', '>= 2.3.2'
+    gem.add_dependency 'bond', '>= 0.1.4'
+    gem.add_development_dependency 'rspec'
+    gem.add_development_dependency 'mocha'
+    gem.add_development_dependency 'fakeweb'
+    
+    
     # 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:
@@ -40,7 +51,7 @@ end
 
 task :default => :spec
 
-require 'hanna/rdoctask'
+require 'rake/rdoctask'
 Rake::RDocTask.new do |rdoc|
   if File.exist?('VERSION.yml')
     config = YAML.load(File.read('VERSION.yml'))

data/VERSION

@@ -1 +1 @@
-0.3.0
+0.3.2

data/acts_as_icontact.gemspec

@@ -1,12 +1,15 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE
+# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
 # -*- encoding: utf-8 -*-
 
 Gem::Specification.new do |s|
   s.name = %q{acts_as_icontact}
-  s.version = "0.3.0"
+  s.version = "0.3.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Stephen Eley"]
-  s.date = %q{2009-08-01}
+  s.date = %q{2009-08-08}
   s.default_executable = %q{icontact}
   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:
 
@@ -40,6 +43,7 @@ Gem::Specification.new do |s|
      "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/campaign.rb",
      "lib/acts_as_icontact/resources/client.rb",
      "lib/acts_as_icontact/resources/contact.rb",
      "lib/acts_as_icontact/resources/custom_field.rb",
@@ -56,7 +60,8 @@ Gem::Specification.new do |s|
      "spec/resource_collection_spec.rb",
      "spec/resource_spec.rb",
      "spec/resources/account_spec.rb",
-     "spec/resources/client_spec.rb",
+     "spec/resources/campaign_spec.rb",
+     "spec/resources/clientfolder_spec.rb",
      "spec/resources/contact_spec.rb",
      "spec/resources/custom_field_spec.rb",
      "spec/resources/list_spec.rb",
@@ -69,7 +74,7 @@ Gem::Specification.new do |s|
      "spec/support/spec_fakeweb.rb"
   ]
   s.homepage = %q{http://github.com/SFEley/acts_as_icontact}
-  s.rdoc_options = ["--charset=UTF-8"]
+  s.rdoc_options = ["--charset=UTF-8", "--all"]
   s.require_paths = ["lib"]
   s.rubyforge_project = %q{actsasicontact}
   s.rubygems_version = %q{1.3.5}
@@ -84,7 +89,8 @@ Gem::Specification.new do |s|
      "spec/resource_collection_spec.rb",
      "spec/resource_spec.rb",
      "spec/resources/account_spec.rb",
-     "spec/resources/client_spec.rb",
+     "spec/resources/campaign_spec.rb",
+     "spec/resources/clientfolder_spec.rb",
      "spec/resources/contact_spec.rb",
      "spec/resources/custom_field_spec.rb",
      "spec/resources/list_spec.rb",
@@ -101,8 +107,26 @@ Gem::Specification.new do |s|
     s.specification_version = 3
 
     if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<rest-client>, [">= 1.0"])
+      s.add_runtime_dependency(%q<activesupport>, [">= 2.3.2"])
+      s.add_runtime_dependency(%q<bond>, [">= 0.1.4"])
+      s.add_development_dependency(%q<rspec>, [">= 0"])
+      s.add_development_dependency(%q<mocha>, [">= 0"])
+      s.add_development_dependency(%q<fakeweb>, [">= 0"])
     else
+      s.add_dependency(%q<rest-client>, [">= 1.0"])
+      s.add_dependency(%q<activesupport>, [">= 2.3.2"])
+      s.add_dependency(%q<bond>, [">= 0.1.4"])
+      s.add_dependency(%q<rspec>, [">= 0"])
+      s.add_dependency(%q<mocha>, [">= 0"])
+      s.add_dependency(%q<fakeweb>, [">= 0"])
     end
   else
+    s.add_dependency(%q<rest-client>, [">= 1.0"])
+    s.add_dependency(%q<activesupport>, [">= 2.3.2"])
+    s.add_dependency(%q<bond>, [">= 0.1.4"])
+    s.add_dependency(%q<rspec>, [">= 0"])
+    s.add_dependency(%q<mocha>, [">= 0"])
+    s.add_dependency(%q<fakeweb>, [">= 0"])
   end
 end

data/bin/icontact

@@ -12,7 +12,7 @@ module ActsAsIcontact
   history_file = File.join(ENV["HOME"], '.icontact_history')
   IO.readlines(history_file).each {|e| Readline::HISTORY << e.chomp } if File.exists?(history_file)
   print "# ActsAsIcontact command line (type 'exit' to quit)\n"
-  while (input = Readline.readline('>> ', true)) != 'exit'
+  while (input = Readline.readline("\n>> ", true)) != 'exit'
     begin puts "=> #{eval(input).inspect}"; rescue Exception; puts "Error: #{$!}" end
   end
   File.open(history_file, 'w') {|f| f.write Readline::HISTORY.to_a.join("\n") }

data/lib/acts_as_icontact/resource.rb

@@ -1,5 +1,6 @@
 require 'activesupport'
 require 'uri'
+require 'YAML'
 
 module ActsAsIcontact
   # Base class for shared functionality between iContact resources.  Supports getting, finding, saving,
@@ -150,6 +151,11 @@ module ActsAsIcontact
       properties == obj.properties
     end
     
+    # Returns a nice formatted string for command line use.
+    def inspect
+      properties.to_yaml
+    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
@@ -173,7 +179,7 @@ module ActsAsIcontact
     # The base RestClient resource that this particular class nests from.  Defaults to 
     # the clientFolders path since that's the most common case.
     def self.base
-      ActsAsIcontact.client
+      ActsAsIcontact.clientfolder
     end
     
     # The name of the singular resource type pulled from iContact.  Defaults to the lowercase

data/lib/acts_as_icontact/resource_collection.rb

@@ -1,15 +1,17 @@
 module ActsAsIcontact
   class ResourceCollection < Enumerator
-    attr_reader :total, :retrieved
+    attr_reader :total, :retrieved, :offset, :collection_name
     
     def initialize(klass, collection, forwardTo=nil)
       @klass = klass
       @forwardTo = forwardTo
       
-      @collection = collection[klass.collection_name]
+      @collection_name = klass.collection_name
+      @collection = collection[collection_name]
       # Get number of elements
       @retrieved = @collection.size
       @total = collection["total"]
+      @offset = collection["offset"]
       
       enumcode = Proc.new do |yielder|
         counter = 0
@@ -32,6 +34,18 @@ module ActsAsIcontact
       self.next
     end
     
+    # Returns a nice formatted string for command line use.
+    def inspect
+      if offset.to_i > 0
+        "#{retrieved} out of #{total} #{collection_name} (offset #{offset})"
+      elsif retrieved != total
+        "#{retrieved} out of #{total} #{collection_name}"
+      else
+        "#{total} #{collection_name}"
+      end
+      
+    end
+    
     private 
     def resource(properties)
       if @forwardTo

data/lib/acts_as_icontact/resources/campaign.rb

@@ -0,0 +1,30 @@
+module ActsAsIcontact
+  class Campaign < Resource
+    
+    # Defaults forwardToFriend to 0; subscriptionManagement, clickTrackMode to true; and useAccountAddress, archiveByDefault to false
+    def initialize(properties={})
+      super({:forwardToFriend => 0,
+             :clickTrackMode => true,
+             :subscriptionManagement => true,
+             :useAccountAddress => false,
+             :archiveByDefault => false}.merge(properties))
+    end
+    
+    # Requires name, fromName, fromEmail, forwardToFriend, subscriptionManagement, clickTrackMode, useAccountAddress, and archiveByDefault
+    def self.required_on_create
+      super + %w(name fromName fromEmail forwardToFriend subscriptionManagement clickTrackMode useAccountAddress archiveByDefault)
+    end
+      
+    # The following can be set with true or false: subscriptionManagement, clickTrackMode, useAccountAddress, archiveByDefault
+    def self.boolean_fields
+      super + %w(subscriptionManagement clickTrackMode useAccountAddress archiveByDefault)
+    end
+    
+    # Returns a collection of all Message resources matching this campaignId.  Additional search options can be passed to further restrict the result set.
+    def messages(options={})
+      search = {:campaignId => id}.merge(options)
+      Message.all(search)
+    end
+    
+  end
+end

data/lib/acts_as_icontact/resources/client.rb

@@ -1,7 +1,7 @@
 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
+  class ClientFolder < Resource
     # Derives from the Account resource.
     def self.base
       ActsAsIcontact.account
@@ -26,25 +26,25 @@ module ActsAsIcontact
   
   # 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
+  def self.clientfolder_id
+    @clientfolder_id ||= ClientFolder.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
+  def self.clientfolder_id=(val)
+    @clientfolder_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}"]
+  def self.clientfolder
+    @clientfolder ||= account["c/#{clientfolder_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
+  def self.reset_clientfolder!
+    @clientfolder = nil
   end
 end

data/lib/acts_as_icontact/resources/contact.rb

@@ -6,11 +6,6 @@ module ActsAsIcontact
       super << 'email'
     end
     
-    # Derived from clientFolder
-    def self.base
-      ActsAsIcontact.client
-    end
-    
     # Defaults to status=total to return contacts on or off lists
     def self.default_options
       super.merge(:status=>:total)

data/lib/acts_as_icontact/resources/list.rb

@@ -1,9 +1,5 @@
 module ActsAsIcontact
   class List < Resource
-    # Derives from clientFolder.
-    def self.base
-      ActsAsIcontact.client
-    end
     
     # Searches on list name.
     def self.find_by_string(value)
@@ -15,6 +11,7 @@ module ActsAsIcontact
       super << "name" << "emailOwnerOnChange" << "welcomeOnManualAdd" << "welcomeOnSignupAdd" << "welcomeMessageId"
     end
     
+    # The following can be set with true or false: emailOwnerOnChange, welcomeOnManualAdd, welcomeOnSignupAdd
     def self.boolean_fields
       super << "emailOwnerOnChange" << "welcomeOnManualAdd" << "welcomeOnSignupAdd"
     end

data/lib/acts_as_icontact/resources/message.rb

@@ -15,5 +15,14 @@ module ActsAsIcontact
       messageType = %w(normal autoresponder welcome confirmation)
       raise ActsAsIcontact::ValidationError, "messageType must be one of: " + messageType.join(', ') unless messageType.include?(fields["messageType"])
     end
+    
+    # Returns the Campaign resource associated with this message, if campaignId is set.  Otherwise returns nil.  Returns an exception if the campaignId is set but the campaign cannot be found.
+    def campaign
+      if (c = campaignId.to_i) > 0
+        Campaign.find(c)
+      else
+        nil
+      end
+    end
   end
 end

data/spec/resource_collection_spec.rb

@@ -24,4 +24,32 @@ describe ActsAsIcontact::ResourceCollection do
     @this.first.foo.should == "bar"
     @this.next.yoo.should == "yar"
   end
+  
+  it "knows its total size" do
+    @this.total.should == 2
+  end
+  
+  it "knows its count" do
+    @this.count.should == 2
+  end
+  
+  it "knows its offset" do
+    @this.offset.should == 0
+  end
+  
+  it "has a nice string representation when all resources are retrieved" do
+    r = ActsAsIcontact::Resource.all
+    r.inspect.should =~ /^12 resources/
+  end
+  
+  it "has a nice string representation when some resources are retrieved" do
+    r = ActsAsIcontact::Resource.all(limit: 5)
+    r.inspect.should =~ /^5 out of 12 resources/
+  end
+  
+  it "has a nice string representation when an offset is used" do
+    r = ActsAsIcontact::Resource.all(limit: 5, offset: 5)
+    r.inspect.should =~ /^5 out of 12 resources \(offset 5\)/
+  end
+    
 end

data/spec/resource_spec.rb

@@ -2,7 +2,7 @@ require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
 
 describe ActsAsIcontact::Resource do
   it "has a RestClient connection" do
-    ActsAsIcontact::Resource.connection.url.should == ActsAsIcontact.client['resources'].url
+    ActsAsIcontact::Resource.connection.url.should == ActsAsIcontact.clientfolder['resources'].url
   end
   
   it "can return all resources for the given URL" do
@@ -13,6 +13,13 @@ describe ActsAsIcontact::Resource do
     ActsAsIcontact::Resource.first.should be_a_kind_of(ActsAsIcontact::Resource)
   end
   
+  it "has a nice string representation" do
+    r = ActsAsIcontact::Resource.first
+    r.inspect.should =~ /foo: bar/m
+    r.inspect.should =~ /resourceId: 1/m
+    r.inspect.should =~ /too: bar/m
+  end
+  
   describe "find method" do
     it "returns a ResourceCollection when given :all" do
       r = ActsAsIcontact::Resource.find(:all)
@@ -104,7 +111,7 @@ describe ActsAsIcontact::Resource do
   
   it "has its own connection if it's not new" do
     r = ActsAsIcontact::Resource.first
-    r.connection.url.should == ActsAsIcontact.client['resources/1'].url
+    r.connection.url.should == ActsAsIcontact.clientfolder['resources/1'].url
   end
   
   it "does not have a connection if it's new" do
@@ -113,7 +120,7 @@ describe ActsAsIcontact::Resource do
   end
   
   it "knows its REST base resource" do
-    ActsAsIcontact::Resource.base.should == ActsAsIcontact.client
+    ActsAsIcontact::Resource.base.should == ActsAsIcontact.clientfolder
   end
   
   it "knows its primary key" do

data/spec/resources/campaign_spec.rb

@@ -0,0 +1,58 @@
+require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+
+describe ActsAsIcontact::Campaign do
+  before(:each) do
+    @contact = ActsAsIcontact::Campaign.new
+  end
+  
+  it "requires a name" do
+    lambda{@contact.save}.should raise_error(ActsAsIcontact::ValidationError, /name/)
+  end
+
+  it "requires a fromName" do
+    lambda{@contact.save}.should raise_error(ActsAsIcontact::ValidationError, /fromName/)
+  end
+
+
+  it "requires a fromEmail" do
+    lambda{@contact.save}.should raise_error(ActsAsIcontact::ValidationError, /fromEmail/)
+  end
+    
+    
+  it "defaults forwardToFriend to 0" do
+    @contact.forwardToFriend.should == 0
+  end
+  
+  it "defaults subscriptionManagement to true" do
+    @contact.subscriptionManagement.should be_true
+  end
+  
+  it "defaults clickTrackMode to true" do
+    @contact.subscriptionManagement.should be_true
+  end
+    
+  it "defaults useAccountAddress to false" do
+    @contact.useAccountAddress.should be_false
+  end
+  
+  it "defaults archiveByDefault to false" do
+    @contact.archiveByDefault.should be_false
+  end
+  
+  context "associations" do
+    before(:each) do
+      @campaign = ActsAsIcontact::Campaign.first
+    end
+  
+    it "knows which messages it has (if any)" do
+      m = @campaign.messages
+      m.count.should == 2
+    end
+    
+    it "can narrow down the messages list" do
+      m = @campaign.messages(messageType: "welcome")
+      m.count.should == 1
+    end
+  end
+    
+end

data/spec/resources/{client_spec.rb → clientfolder_spec.rb}

@@ -2,51 +2,51 @@ require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
 
 describe ActsAsIcontact, "account_id" do
   it "returns the ID from the first client folder returned by iContact" do
-    ActsAsIcontact.client_id.should == 222222
+    ActsAsIcontact.clientfolder_id.should == 222222
   end
   
   it "can be set by the user" do
-    ActsAsIcontact.client_id = 456
-    ActsAsIcontact.client_id.should == 456
+    ActsAsIcontact.clientfolder_id = 456
+    ActsAsIcontact.clientfolder_id.should == 456
   end
   
   after(:each) do
-    ActsAsIcontact.client_id = nil
+    ActsAsIcontact.clientfolder_id = nil
   end
 end
 
 
-describe ActsAsIcontact, "client method" do
+describe ActsAsIcontact, "clientfolder method" do
   it "returns a RestClient resource" do
-    ActsAsIcontact.client.should be_a_kind_of(RestClient::Resource)
+    ActsAsIcontact.clientfolder.should be_a_kind_of(RestClient::Resource)
   end
   
   it "builds upon the 'account' object" do
     ActsAsIcontact.expects(:account).returns(ActsAsIcontact.instance_variable_get(:@account))
-    ActsAsIcontact.client.should_not be_nil
+    ActsAsIcontact.clientfolder.should_not be_nil
   end
   
   it "can be cleared with the reset_account! method" do
-    ActsAsIcontact.reset_client!
-    ActsAsIcontact.instance_variable_get(:@client).should be_nil
+    ActsAsIcontact.reset_clientfolder!
+    ActsAsIcontact.instance_variable_get(:@clientfolder).should be_nil
   end
   
   after(:each) do
-    ActsAsIcontact.reset_client!
+    ActsAsIcontact.reset_clientfolder!
   end
 end
 
-describe ActsAsIcontact::Client do
+describe ActsAsIcontact::ClientFolder do
   it "can return all clients for the given account" do
-    ActsAsIcontact::Client.all.count.should == 1
+    ActsAsIcontact::ClientFolder.all.count.should == 1
   end
   
   it "can return the first client" do
-    ActsAsIcontact::Client.first.should be_a_kind_of(ActsAsIcontact::Client)
+    ActsAsIcontact::ClientFolder.first.should be_a_kind_of(ActsAsIcontact::ClientFolder)
   end
     
   it "knows its properties" do
-    c = ActsAsIcontact::Client.first
+    c = ActsAsIcontact::ClientFolder.first
     c.emailRecipient.should == "bob@example.org"
   end
 end

data/spec/resources/message_spec.rb

@@ -22,7 +22,9 @@ describe ActsAsIcontact::Message do
       @message = ActsAsIcontact::Message.first(:subject => "Test Message")
     end
   
-    it "knows which campaign it has (if any)"
+    it "knows which campaign it has (if any)" do
+      @message.campaign.name.should == "Test Campaign"
+    end 
   end
     
 end

data/spec/support/spec_fakeweb.rb

@@ -7,7 +7,7 @@ ic = "#{i}/a/111111/c/222222"
 
 # Resources (this one's a fake stub for pure testing)
 FakeWeb.register_uri(:get, "#{ic}/resources?limit=500", :body => %q<{"resources":[{"foo":"bar","resourceId":"1","too":"bar"},{"foo":"aar","resourceId":"2"},{"foo":"far","resourceId":"3"},{"foo":"car","resourceId":"4"},{"foo":"dar","resourceId":"5"},{"foo":"ear","resourceId":"6"},{"foo":"gar","resourceId":"7"},{"foo":"har","resourceId":"8"},{"foo":"iar","resourceId":"9"},{"foo":"jar","resourceId":"10"},{"foo":"kar","resourceId":"11"},{"foo":"yar","resourceId":"12"}],"total":12,"limit":20,"offset":0}>)
-FakeWeb.register_uri(:get, "#{ic}/resources?limit=1", :body => %q<{"resources":[{"foo":"bar","resourceId":"1","too":"bar"},{"foo":"aar","resourceId":"2"},{"foo":"far","resourceId":"3"},{"foo":"car","resourceId":"4"},{"foo":"dar","resourceId":"5"},{"foo":"ear","resourceId":"6"},{"foo":"gar","resourceId":"7"},{"foo":"har","resourceId":"8"},{"foo":"iar","resourceId":"9"},{"foo":"jar","resourceId":"10"},{"foo":"kar","resourceId":"11"},{"foo":"yar","resourceId":"12"}],"total":12,"limit":20,"offset":0}>)
+FakeWeb.register_uri(:get, "#{ic}/resources?limit=1", :body => %q<{"resources":[{"foo":"bar","resourceId":"1","too":"bar"}],"total":12,"limit":1,"offset":0}>)
 FakeWeb.register_uri(:get, "#{ic}/resources?limit=5", :body => %q<{"resources":[{"foo":"bar","resourceId":"1"},{"foo":"aar","resourceId":"2"},{"foo":"far","resourceId":"3"},{"foo":"car","resourceId":"4"},{"foo":"dar","resourceId":"5"}],"total":12,"limit":5,"offset":0}>)
 FakeWeb.register_uri(:get, "#{ic}/resources?limit=500&offset=5", :body => %q<{"resources":[{"foo":"ear","resourceId":"6"},{"foo":"gar","resourceId":"7"},{"foo":"har","resourceId":"8"},{"foo":"iar","resourceId":"9"},{"foo":"jar","resourceId":"10"},{"foo":"kar","resourceId":"11"},{"foo":"yar","resourceId":"12"}],"total":12,"limit":20,"offset":5}>)
 FakeWeb.register_uri(:get, "#{ic}/resources?offset=5&limit=5", :body => %q<{"resources":[{"foo":"ear","resourceId":"6"},{"foo":"gar","resourceId":"7"},{"foo":"har","resourceId":"8"},{"foo":"iar","resourceId":"9"},{"foo":"jar","resourceId":"10"}],"total":12,"limit":5,"offset":5}>)
@@ -40,12 +40,14 @@ FakeWeb.register_uri(:get, "#{ic}/lists/444444", :body => %q<{"list":{"listId":"
 
 # Message
 #### Test welcome message for List association
-FakeWeb.register_uri(:get, "#{ic}/messages/555555", :body => %q<{"message":{"messageId":"555555","subject":"Welcome!","messageType":"welcome","textBody":"Welcome to the Test List!","htmlBody":"<p>Welcome to the <b>Test List</b>!</p>","createDate":"20090725 14:55:12"}}>)
+FakeWeb.register_uri(:get, "#{ic}/messages/555555", :body => %q<{"message":{"messageId":"555555","subject":"Welcome!","messageType":"welcome","textBody":"Welcome to the Test List!","htmlBody":"<p>Welcome to the <b>Test List</b>!</p>","createDate":"20090725 14:55:12","campaignId":"777777"}}>)
 #### Test confirmation message
-FakeWeb.register_uri(:get, "#{ic}/messages/555666", :body => %q<{"message":{"messageId":"555666","subject":"Confirm!","messageType":"confirmation","textBody":"Please confirm your subscription.","htmlBody":"<p>Please confirm your subscription.</p>","createDate":"20090727 14:55:12"}}>)
-
+FakeWeb.register_uri(:get, "#{ic}/messages/555666", :body => %q<{"message":{"messageId":"555666","subject":"Confirm!","messageType":"confirmation","textBody":"Please confirm your subscription.","htmlBody":"<p>Please confirm your subscription.</p>","createDate":"20090727 14:55:12","campaignId":"777777"}}>)
+#### Searches from campaignId
+FakeWeb.register_uri(:get, "#{ic}/messages?limit=500&campaignId=777777", :body => %q<{"messages":[{"messageId":"555555","subject":"Welcome!","messageType":"welcome","textBody":"Welcome to the Test List!","htmlBody":"<p>Welcome to the <b>Test List</b>!</p>","createDate":"20090725 14:55:12","campaignId":"777777"},{"messageId":"555666","subject":"Confirm!","messageType":"confirmation","textBody":"Please confirm your subscription.","htmlBody":"<p>Please confirm your subscription.</p>","createDate":"20090727 14:55:12","campaignId":"777777"}],"count":2}>)
+FakeWeb.register_uri(:get, "#{ic}/messages?limit=500&campaignId=777777&messageType=welcome", :body => %q<{"messages":[{"messageId":"555555","subject":"Welcome!","messageType":"welcome","textBody":"Welcome to the Test List!","htmlBody":"<p>Welcome to the <b>Test List</b>!</p>","createDate":"20090725 14:55:12","campaignId":"777777"}],"count":1}>)
 #### Test message for associations originating from Message spec
-FakeWeb.register_uri(:get, "#{ic}/messages?limit=1&subject=Test%20Message", :body => %q<{"messages":[{"messageId":"666666","subject":"Test Message","messageType":"normal","textBody":"Hi there!\nThis is just a test.","htmlBody":"<p><b>Hi there!</b></p><p>This is just a <i>test.</i></p>","createDate":"20090725 14:53:33"}]}>)
+FakeWeb.register_uri(:get, "#{ic}/messages?limit=1&subject=Test%20Message", :body => %q<{"messages":[{"messageId":"666666","subject":"Test Message","messageType":"normal","textBody":"Hi there!\nThis is just a test.","htmlBody":"<p><b>Hi there!</b></p><p>This is just a <i>test.</i></p>","createDate":"20090725 14:53:33","campaignId":"777777"}]}>)
 
 # CustomField
 FakeWeb.register_uri(:get, "#{ic}/customfields?limit=500", :body => %q<{"customfields":[{"privateName":"test_field","publicName":"Test Field","displayToUser":"0","fieldType":"text"},{"privateName":"custom_field","publicName":"This is for the Rails integration specs","displayToUser":1,"fieldType":"text"}],"total":2}>)
@@ -60,3 +62,7 @@ FakeWeb.register_uri(:get, "#{ic}/subscriptions?limit=1&contactId=333444", :body
 FakeWeb.register_uri(:get, "#{ic}/subscriptions?limit=500&contactId=333444", :body => %q<{"subscriptions":[{"status":"normal","addDate":"2009-07-27T15:36:37-04:00","contactId":333444,"listId":444444, "subscriptionId":"444444_333444","confirmationMessageId":555666}]}>)
 FakeWeb.register_uri(:get, "#{ic}/subscriptions?limit=500&contactId=333333", :body => %q<{"subscriptions":[{"status":"normal","addDate":"2009-07-27T15:36:37-04:00","contactId":333333,"listId":444444, "subscriptionId":"444444_333333","confirmationMessageId":555666}]}>)
 FakeWeb.register_uri(:post, "#{ic}/subscriptions", :body => %q<{"subscriptions":[{"status":"normal","addDate":"2009-07-27T15:36:37-04:00","contactId":333333,"listId":444444, "subscriptionId":"444444_333333","confirmationMessageId":555666}]}>)
+
+# Campaign
+FakeWeb.register_uri(:get, "#{ic}/campaigns?limit=1", :body => %q<{"campaigns":[{"campaignId":"777777","name":"Test Campaign","fromName":"Bob Smith","fromEmail":"bob@example.org","forwardToFriend":0,"subscriptionManagement":1,"clickTrackMode":1,"useAccountAddress":0,"archiveByDefault":0,"description":""}],"count":1}>)
+FakeWeb.register_uri(:get, "#{ic}/campaigns/777777", :body => %q<{"campaign":{"campaignId":"777777","name":"Test Campaign","fromName":"Bob Smith","fromEmail":"bob@example.org","forwardToFriend":0,"subscriptionManagement":1,"clickTrackMode":1,"useAccountAddress":0,"archiveByDefault":0,"description":""}}>)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: acts_as_icontact
 version: !ruby/object:Gem::Version 
-  version: 0.3.0
+  version: 0.3.2
 platform: ruby
 authors: 
 - Stephen Eley
@@ -9,10 +9,69 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-08-01 00:00:00 -04:00
+date: 2009-08-08 00:00:00 -04:00
 default_executable: icontact
-dependencies: []
-
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rest-client
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "1.0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.3.2
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: bond
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.1.4
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: mocha
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: fakeweb
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
 description: |
   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:
   
@@ -48,6 +107,7 @@ files:
 - 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/campaign.rb
 - lib/acts_as_icontact/resources/client.rb
 - lib/acts_as_icontact/resources/contact.rb
 - lib/acts_as_icontact/resources/custom_field.rb
@@ -64,7 +124,8 @@ files:
 - spec/resource_collection_spec.rb
 - spec/resource_spec.rb
 - spec/resources/account_spec.rb
-- spec/resources/client_spec.rb
+- spec/resources/campaign_spec.rb
+- spec/resources/clientfolder_spec.rb
 - spec/resources/contact_spec.rb
 - spec/resources/custom_field_spec.rb
 - spec/resources/list_spec.rb
@@ -82,6 +143,7 @@ licenses: []
 post_install_message: 
 rdoc_options: 
 - --charset=UTF-8
+- --all
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
@@ -113,7 +175,8 @@ test_files:
 - spec/resource_collection_spec.rb
 - spec/resource_spec.rb
 - spec/resources/account_spec.rb
-- spec/resources/client_spec.rb
+- spec/resources/campaign_spec.rb
+- spec/resources/clientfolder_spec.rb
 - spec/resources/contact_spec.rb
 - spec/resources/custom_field_spec.rb
 - spec/resources/list_spec.rb