has_emails 0.0.1

data/CHANGELOG

@@ -0,0 +1,23 @@
+*SVN*
+
+*0.0.1* (September 26th, 2007)
+
+* Refactor has_email_address/has_email_addresses so that new associations for unsent/sent emails isn't created for has_email_address
+
+* Add state changes fixtures for tests
+
+* Add tests for ApplicationMailer
+
+* Add support for tracking the original email address for senders/recipients even if the email address changes on the associated model (i.e. EmailAddress/User/etc.)
+
+* Support converting models with an email_address/email_addresses association
+
+* Allow the sender of emails to be an arbitrary string email address
+
+* Add documentation
+
+* Move test fixtures out of the test application root directory
+
+* Convert dos newlines to unix newlines
+
+* Update against latest changes to has_messages

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2006-2007 Aaron Pfeifer & Neil Abraham
+
+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

@@ -0,0 +1,130 @@
+= has_emails
+
++has_emails+ adds support for emailing capabilities between ActiveRecord models.
+
+== Resources
+
+API
+
+* http://api.pluginaweek.org/has_emails
+
+Wiki
+
+* http://wiki.pluginaweek.org/Has_emails
+
+Announcement
+
+* http://www.pluginaweek.org
+
+Source
+
+* http://svn.pluginaweek.org/trunk/plugins/active_record/has/has_emails
+
+Development
+
+* http://dev.pluginaweek.org/browser/trunk/plugins/active_record/has/has_emails
+
+== Description
+
+Emailing between users and other parts of a system is a fairly common feature in
+web applications, especially for those that support social networking.  Emailing
+doesn't necessarily need to be between users, but can also act as a way for the
+web application to send notices and other notifications to users.
+
+Rails already provides ActionMailer as a way of sending emails.  However, the
+framework does not provide an easy way to persist emails, track their status, and
+process them asynchronously.  Designing and building this type of framework can
+become complex and cumbersome and takes away from the focus of the web application.
+This plugin helps ease that process by providing a complete implementation for
+sending and receiving emails to and between models in your application.
+
+== Usage
+
+=== Adding emailing support
+
+If you want to use the built-in support for email addresses (using the EmailAddress
+model), you can add emailing support for users like so:
+
+  class User < ActiveRecord::Base
+    has_email_address
+    # has_email_addresses if you want to support multiple addresses
+  end
+
+On the other hand, if you already have the email address for users stored as a
+column in your users table, you can add emailing support like so:
+
+  class User < ActiveRecord::Base
+    has_messages  :emails,
+                    :message_class => 'Email'
+  end
+
+=== Creating new emails
+
+  email = user.emails.build
+  email.to << [user1, email_address1, 'someone@somewhere.com']
+  email.subject = 'Hey!'
+  email.body = 'Does anyone want to go out tonight?'
+  email.deliver!
+
+As can be seen in the above example, you can use Users, EmailAddresses, or even
+Strings as recipients in emails.  Each will be automatically converted to the
+EmailRecipient class so that it can be stored in the database.
+
+=== Replying to emails
+
+  reply = email.reply_to_all
+  reply.body = "I'd love to go out!"
+  reply.deliver!
+
+=== Forwarding emails
+
+  forward = email.forward
+  forward.body = 'Interested?'
+  forward.deliver!
+
+=== External process messaging
+
+In addition to delivering emails immediately, you can also *queue* emails so
+that an external application processes and delivers them.  This is especially
+useful when you want to asynchronously send e-mails so that it doesn't block the
+user interface on your web application.
+
+To queue emails for external processing, you can simply use the <tt>queue!</tt>
+event, rather than <tt>deliver!</tt>.  This will indicate to any external processes
+that the email is ready to be sent.  The external process can then invoke <tt>deliver!</tt>
+whenever it is ready to send the queued email.
+
+=== Running migrations
+
+To migrate the tables required for this plugin, you can either run the
+migration from the command line like so:
+
+  rake db:migrate:plugins PLUGIN=has_emails
+
+or (more ideally) generate a migration file that will integrate into your main
+application's migration path:
+
+  ruby script/generate plugin_migration has_emails
+
+== Testing
+
+Before you can run any tests, the following gems must be installed:
+* plugin_test_helper[http://wiki.pluginaweek.org/Plugin_test_helper]
+* dry_validity_assertions[http://wiki.pluginaweek.org/Dry_validity_assertions]
+
+== Dependencies
+
+This plugin depends on the presence of the following plugins:
+* has_messages[http://wiki.pluginaweek.org/Has_messages]
+
+This plugin is also a plugin+.  That means that it contains a slice of an
+application, such as models and migrations.  To test or use a plugin+, you
+must have the following plugins/gems installed:
+* plugin_dependencies[http://wiki.pluginaweek.org/Plugin_dependencies]
+* loaded_plugins[http://wiki.pluginaweek.org/Loaded_plugins]
+* appable_plugins[http://wiki.pluginaweek.org/Appable_plugins]
+* plugin_migrations[http://wiki.pluginaweek.org/Plugin_migrations]
+
+Instead of installing each individual plugin+ feature, you can install them all
+at once using the plugins+[http://wiki.pluginaweek.org/Plugins_plus] meta package,
+which contains all additional features.

data/Rakefile

@@ -0,0 +1,81 @@
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'rake/contrib/sshpublisher'
+
+PKG_NAME           = 'has_emails'
+PKG_VERSION        = '0.0.1'
+PKG_FILE_NAME      = "#{PKG_NAME}-#{PKG_VERSION}"
+RUBY_FORGE_PROJECT = 'pluginaweek'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the has_emails plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the has_emails plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'HasEmails'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+spec = Gem::Specification.new do |s|
+  s.name            = PKG_NAME
+  s.version         = PKG_VERSION
+  s.platform        = Gem::Platform::RUBY
+  s.summary         = 'Adds support for emailing capabilities between ActiveRecord models.'
+  
+  s.files           = FileList['{app,db,lib,test}/**/*'].to_a + %w(CHANGELOG init.rb MIT-LICENSE Rakefile README)
+  s.require_path    = 'lib'
+  s.autorequire     = 'has_emails'
+  s.has_rdoc        = true
+  s.test_files      = Dir['test/**/*_test.rb']
+  s.add_dependency  'has_messages', '>= 0.0.1'
+  s.add_dependency  'validates_as_email_address', '>= 0.0.1'
+  
+  s.author          = 'Aaron Pfeifer, Neil Abraham'
+  s.email           = 'info@pluginaweek.org'
+  s.homepage        = 'http://www.pluginaweek.org'
+end
+  
+Rake::GemPackageTask.new(spec) do |p|
+  p.gem_spec = spec
+  p.need_tar = true
+  p.need_zip = true
+end
+
+desc 'Publish the beta gem'
+task :pgem => [:package] do
+  Rake::SshFilePublisher.new('pluginaweek@pluginaweek.org', '/home/pluginaweek/gems.pluginaweek.org/gems', 'pkg', "#{PKG_FILE_NAME}.gem").upload
+end
+
+desc 'Publish the API documentation'
+task :pdoc => [:rdoc] do
+  Rake::SshDirPublisher.new('pluginaweek@pluginaweek.org', "/home/pluginaweek/api.pluginaweek.org/#{PKG_NAME}", 'rdoc').upload
+end
+
+desc 'Publish the API docs and gem'
+task :publish => [:pdoc, :release]
+
+desc 'Publish the release files to RubyForge.'
+task :release => [:gem, :package] do
+  require 'rubyforge'
+  
+  ruby_forge = RubyForge.new
+  ruby_forge.login
+  
+  %w( gem tgz zip ).each do |ext|
+    file = "pkg/#{PKG_FILE_NAME}.#{ext}"
+    puts "Releasing #{File.basename(file)}..."
+    
+    ruby_forge.add_release(RUBY_FORGE_PROJECT, PKG_NAME, PKG_VERSION, file)
+  end
+end

data/app/mailers/application_mailer.rb

@@ -0,0 +1,85 @@
+# Provides base operations for emailing
+class ApplicationMailer < ActionMailer::Base
+  @@default_subject_prefix = "[#{File.basename(File.expand_path(RAILS_ROOT)).camelize}] "
+  cattr_accessor :default_subject_prefix
+  
+  # Specify the prefix to use for the subject. This defaults to the
+  # +default_subject_prefix+ specified for ApplicationMailer.
+  adv_attr_accessor :subject_prefix
+  
+  class << self
+    def method_missing(method_symbol, *parameters) #:nodoc:
+      case method_symbol.id2name
+        when /^queue_([_a-z]\w*)/ then new($1, *parameters).queue
+        else super
+      end
+    end
+  end
+  
+  alias_method :to, :recipients
+  
+  # Sets or gets the subject of the email.  All subjects are prefixed with a
+  # value indicating the application it is coming from.
+  def subject(*parameters)
+    if parameters.empty?
+      super
+    else
+      super(subject_prefix + super)
+    end
+  end
+  alias_method :subject=, :subject
+  
+  # Delivers an email based on the content in the specified email
+  def email(email)
+    @from       = email.sender
+    @recipients = email.to
+    @cc         = email.cc
+    @bcc        = email.bcc
+    @subject    = email.subject
+    @body       = email.body
+    @sent_on    = email.sent_at || Time.now
+  end
+  
+  # Queues the current e-mail that has been constructed
+  def queue
+    Email.transaction do
+      # Create the main email
+      email = Email.create!(
+        :sender => from,
+        :subject => subject,
+        :body => body
+      )
+      
+      # Add recipients
+      email.to = [to].flatten
+      email.cc = [cc].flatten
+      email.bcc = [bcc].flatten
+      email.queue!
+    end
+  end
+  
+  private
+  def initialize_defaults(method_name) #:nodoc
+    @sent_on ||= Time.now
+    @subject_prefix ||= @@default_subject_prefix.dup
+    @recipients ||= []
+    @cc ||= []
+    @bcc ||= []
+    
+    super
+  end
+  
+  def quote_address_if_necessary_with_conversion(address, charset) #:nodoc
+    # Uses is_a? instead of === because of AssociationProxy
+    if !address.is_a?(Array)
+      if EmailAddress === address || EmailRecipient === address
+        address = address.with_name
+      elsif !(String === address)
+        address = EmailAddress.convert_from(address).to_s
+      end
+    end
+    
+    quote_address_if_necessary_without_conversion(address, charset)
+  end
+  alias_method_chain :quote_address_if_necessary, :conversion
+end

data/app/models/email.rb

@@ -0,0 +1,84 @@
+# Represents an email which has been sent to one or more recipients.  This is
+# essentially the same as the Message class, but overrides the +to+, +cc+, and +bcc+
+# associations to that proper instances of the MessageRecipient class are created.
+class Email < Message
+  validates_presence_of       :sender_spec
+  validates_as_email_address  :sender_spec,
+                                :allow_nil => true
+  
+  with_options(
+    :class_name => 'EmailRecipient',
+    :foreign_key => 'message_id',
+    :order => 'position ASC',
+    :dependent => true
+  ) do |e|
+    e.has_many  :to,
+                  :conditions => ['kind = ?', 'to'],
+                  :extend => [MessageRecipientToBuildExtension, EmailRecipientBuildExtension]
+    e.has_many  :cc,
+                  :conditions => ['kind = ?', 'cc'],
+                  :extend => [MessageRecipientCcBuildExtension, EmailRecipientBuildExtension]
+    e.has_many  :bcc,
+                  :conditions => ['kind = ?', 'bcc'],
+                  :extend => [MessageRecipientBccBuildExtension, EmailRecipientBuildExtension]
+  end
+  
+  # Returns the sender of the message.  This can be a string if being sent
+  # from an arbitrary e-mail address.
+  def sender_with_spec
+    sender_without_spec || sender_spec
+  end
+  alias_method_chain :sender, :spec
+  
+  # If sender is a string, then sets the spec, otherwise uses the original
+  # sender setter
+  def sender_with_spec=(value)
+    self.sender_spec = EmailAddress.convert_from(value).spec
+    self.sender_without_spec = value if !value.is_a?(String)
+  end
+  alias_method_chain :sender=, :spec
+  
+  # Converts the sender into an Email Address, whether it be a string,
+  # EmailAddress, or other model type
+  def sender_email_address
+    EmailAddress.convert_from(sender_spec)
+  end
+  
+  # The name of the person whose sending the email
+  def sender_name
+    sender_without_spec ? EmailAddress.convert_from(sender_without_spec).name : sender_email_address.name
+  end
+  
+  # Returns a string version of the email address plus any name like
+  # "John Doe <john.doe@gmail.com>"..
+  def sender_with_name
+    address = self.email_address
+    address.name = self.name
+    address.with_name
+  end
+  
+  # Actually delivers the email to the recipients
+  def deliver
+    ApplicationMailer.deliver_email(self)
+  end
+  
+  # Saves the +sender_spec+ in the forwarded message
+  def forward
+    message = super
+    message.sender_spec = sender_spec
+    message
+  end
+  
+  # Saves the +sender_spec+ in the replied message
+  def reply
+    message = super
+    message.sender_spec = sender_spec
+    message
+  end
+  
+  private
+  # Strings are allowed to participate in messaging
+  def model_participant?
+    sender_id && sender_type || sender_spec.nil?
+  end
+end

data/app/models/email_address.rb

@@ -0,0 +1,123 @@
+# Represents a valid RFC822 email address
+class EmailAddress < ActiveRecord::Base
+  class << self
+    # Converts the specified record to an EmailAddress.  It will convert the
+    # following types:
+    # 1. String
+    # 2. A record with an +email_address+ String attribute
+    # 3. A record with an +email_address+ association
+    # 4. A record with an +email_addresses+ association (first record will be chosen)
+    # 
+    # If an EmailAddress is specified, the same model will be returned.  An
+    # ArgumentError is raised if it doesn't match any of the above criteria.
+    def convert_from(record)
+      if record
+        if EmailAddress === record
+          record
+        elsif String === record
+          EmailAddress.new(:spec => record)
+        elsif record.respond_to?(:email_address)
+          if record.email_address.is_a?(String)
+            address = EmailAddress.new(:spec => record.email_address)
+            address.name = record.name if record.respond_to?(:name)
+            address
+          else
+            record.email_address
+          end
+        elsif record.respond_to?(:email_addresses)
+          record.email_addresses.first
+        else
+          raise ArgumentError, "Cannot convert #{record.class} to an EmailAddress"
+        end
+      end
+    end
+    
+    # Determines if the given spec is a valid address using the RFC822 spec
+    def valid?(spec)
+      !RFC822::EmailAddress.match(spec).nil?
+    end
+  end
+  
+  acts_as_tokenized :token_field => 'verification_code', :token_length => 32
+  
+  # Support e-mail address verification
+  has_states    :initial => :unverified
+  
+  # Add messaging capabilities.  This will give us an email_box.
+  has_messages  :emails,
+                  :message_class => 'Email'
+  belongs_to    :emailable,
+                  :polymorphic => true
+  
+  validates_presence_of       :spec
+  
+  with_options(:allow_nil => true) do |klass|
+    klass.validates_uniqueness_of     :spec
+    klass.validates_as_email_address  :spec
+  end
+  
+  # The name of the person who owns this email address
+  attr_accessor :name
+  
+  # Ensure that the e-mail address has a verification code that can be sent
+  # to the user
+  before_create :set_code_expiry
+  
+  state :unverified, :verified
+  
+  # Verifies that the email address is valid
+  event :verify do
+    transition_to :verified, :from => :unverified
+  end
+  
+  # Sets the full address
+  def spec=(new_spec)
+    @local_name = @domain = nil
+    write_attribute(:spec, new_spec)
+  end
+  
+  # The part of the e-mail address before the @
+  def local_name
+    parse_spec if !@local_name
+    @local_name
+  end
+  
+  # The part of the e-mail address after the @
+  def domain
+    parse_spec if !@domain
+    @domain
+  end
+  
+  # Gets the name of the person whose email address this is.  Default is an
+  # empty string.  Override this if you want it to appear in with_name
+  def name
+    @name || ''
+  end
+  
+  # Returns a string version of the email address plus any name like
+  # "John Doe <john.doe@gmail.com>".  In order to have a valid name within the
+  # string, you must override +name+.
+  def with_name
+    name.blank? ? to_s : "#{name} <#{to_s}>"
+  end
+  
+  # Returns the full email address (without the name)
+  def to_s #:nodoc
+    spec
+  end
+  
+  private
+  # Sets the time at which the verification code will expire
+  def set_code_expiry
+    self.code_expiry = 48.hour.from_now
+  end
+  
+  # Parses the current spec and sets +@local_name+ and +@domain+ based on the
+  # matching groups within the regular expression
+  def parse_spec
+    if !@local_name && !@domain && match = RFC822::EmailAddress.match(spec)
+      @local_name = match.captures[0]
+      @domain = match.captures[1]
+    end
+  end
+end

data/app/models/email_recipient.rb

@@ -0,0 +1,78 @@
+# Represents a recipient on an email
+class EmailRecipient < MessageRecipient
+  validates_presence_of       :receiver_spec
+  validates_as_email_address  :receiver_spec,
+                                :allow_nil => true
+  
+  before_save :ensure_exclusive_references
+  
+  # Alias for domain-specific language
+  alias_method    :email, :message
+  alias_method    :email=, :message=
+  alias_attribute :email_id, :message_id
+  
+  delegate  :to_s,
+              :to => :email_address
+  
+  # Returns the receiver of the message.  This can be a string if being sent
+  # to an arbitrary e-mail address.
+  def receiver_with_spec
+    receiver_without_spec || receiver_spec
+  end
+  alias_method_chain :receiver, :spec
+  
+  # If receiver is a string, then sets the spec, otherwise uses the original
+  # receiver setter
+  def receiver_with_spec=(value)
+    self.receiver_spec = EmailAddress.convert_from(value).spec
+    self.receiver_without_spec = value if !value.is_a?(String)
+  end
+  alias_method_chain :receiver=, :spec
+  
+  # Converts the receiver into an Email Address, whether it be a string,
+  # EmailAddress, or other model type
+  def email_address
+    EmailAddress.convert_from(receiver_spec)
+  end
+  
+  # The name of the person whose receiving the email
+  def name
+    receiver_without_spec ? EmailAddress.convert_from(receiver_without_spec).name : email_address.name
+  end
+  
+  # Returns a string version of the email address plus any name like
+  # "John Doe <john.doe@gmail.com>"..
+  def with_name
+    address = self.email_address
+    address.name = self.name
+    address.with_name
+  end
+  
+  private
+  def validate_on_create #:nodoc:
+    begin
+      email_address if receiver
+      true
+    rescue ArgumentError
+      errors.add 'receiver_id', 'must be a string, have a email_address attribute, or be a class that has_email_addresses'
+    end
+  end
+  
+  # Strings are allowed to participate in messaging
+  def model_participant?
+    receiver_id && receiver_type || receiver_spec.nil?
+  end
+  
+  # Ensures that the country id/user region combo is not set at the same time as
+  # the region id
+  def ensure_exclusive_references
+    if model_participant?
+      self.receiver_spec = nil
+    else
+      self.receiver_id = nil
+      self.receiver_type = nil
+    end
+    
+    true
+  end
+end

data/app/models/email_recipient_build_extension.rb

@@ -0,0 +1,7 @@
+module EmailRecipientBuildExtension #:nodoc:
+  # Checks if the recipient and record are equal, using the recipient's
+  # email_address
+  def is_recipient_equal?(recipient, record) #:nodoc:
+    recipient.email_address.to_s == EmailAddress.convert_from(record).to_s
+  end
+end

data/db/bootstrap/events.yml

@@ -0,0 +1,4 @@
+verify:
+  id: 601
+  name: verify
+  owner_type: EmailAddress

data/db/bootstrap/states.yml

@@ -0,0 +1,9 @@
+unverified:
+  id: 601
+  name: unverified
+  owner_type: EmailAddress
+  
+verified:
+  id: 602
+  name: verified
+  owner_type: EmailAddress

data/db/migrate/001_create_email_addresses.rb

@@ -0,0 +1,23 @@
+class CreateEmailAddresses < ActiveRecord::Migration
+  def self.up
+    create_table :email_addresses do |t|
+      t.column :emailable_id, :integer, :null => false, :references => nil
+      t.column :emailable_type, :string, :null => false
+      t.column :spec, :string, :null => false, :limit => 382
+      t.column :verification_code, :string, :limit => 40
+      t.column :code_expiry, :datetime
+      t.column :created_at, :timestamp, :null => false
+      t.column :updated_at, :datetime, :null => false
+    end
+    add_index :email_addresses, :spec, :unique => true
+    add_index :email_addresses, :verification_code, :unique => true
+    
+    PluginAWeek::Has::States.migrate_up(:email_addresses)
+  end
+  
+  def self.down
+    PluginAWeek::Has::States.migrate_down(:email_addresses)
+    
+    drop_table :email_addresses
+  end
+end

data/db/migrate/002_add_email_specs.rb

@@ -0,0 +1,18 @@
+class AddEmailSpecs < ActiveRecord::Migration
+  def self.up
+    # Workaround change_column not allowing change to :null => true
+    remove_column :messages, :sender_id
+    remove_column :messages, :sender_type
+    
+    add_column :messages, :sender_id, :integer, :null => true, :default => nil, :references => nil
+    add_column :messages, :sender_type, :string, :null => true, :default => nil
+    add_column :messages, :sender_spec, :string, :limit => 320
+  end
+
+  def self.down
+    remove_column :messages, :sender_spec
+    
+    change_column :messages, :sender_id, :integer, :null => false, :references => nil
+    change_column :messages, :sender_type, :string, :null => false
+  end
+end