mailboxer 0.0.2

data/.gitignore

@@ -0,0 +1,12 @@
+.bundle/
+log/*.log
+pkg/
+spec/dummy/db/*.sqlite3
+spec/dummy/log/*.log
+spec/dummy/tmp/
+**.tmp_*
+Gemfile.lock
+.idea
+.project
+.document
+.settings/

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+     
+gemspec

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Eduardo Casanova Cuesta
+
+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.rdoc

@@ -0,0 +1,7 @@
+= Mailboxer
+
+This project is based on the need of a private message system for {ging / social_stream}[https://github.com/ging/social_stream]. Instead of creating our core message system heavily dependent on our development we are trying to implement a generic and potent messaging gem.
+
+It is born from the great, but old, code from {lpsergi / acts_as_messageable}[https://github.com/psergi/acts_as_messageable].
+
+There is a lack of documentaion and it will be solved as soon as the gem is more stable and had proved to be useful integrated with SocialStream.

data/Rakefile

@@ -0,0 +1,53 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "mailboxer"
+  gem.homepage = "http://github.com/roendal/mailboxer"
+  gem.license = "MIT"
+  gem.summary = %Q{Private messaging system for rails apps.}
+  gem.description = %Q{TODO: longer description of your gem}
+  gem.email = "ecasanovac@gmail.com"
+  gem.authors = ["Eduardo Casanova Cuesta"]
+  # Include your dependencies below. Runtime dependencies are required when using your gem,
+  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
+  #  gem.add_runtime_dependency 'jabber4r', '> 0.1'
+  #  gem.add_development_dependency 'rspec', '> 1.2.3'
+  gem.add_development_dependency('rspec-rails', '~> 2.4.1')
+  gem.add_development_dependency('factory_girl', '~> 1.3.2')
+  gem.add_development_dependency('forgery', '~> 0.3.6')
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "mailboxer #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.0

data/app/models/mailboxer_conversation.rb

@@ -0,0 +1,60 @@
+class MailboxerConversation < ActiveRecord::Base
+  attr_reader :originator, :original_message, :last_sender, :last_message, :users
+  has_many :mailboxer_messages
+  has_many :mailboxer_mails, :through => :mailboxer_messages
+  before_create :clean
+  scope :participant, lambda {|participant|
+    joins(:mailboxer_messages,:mailboxer_mails).select('DISTINCT mailboxer_conversations.*').where('mailboxer_mails.receiver_id' => participant.id,'mailboxer_mails.receiver_type' => participant.class.to_s)    
+  }
+  
+  #originator of the conversation.
+  def originator
+    @orignator = self.original_message.sender if @originator.nil?
+    return @orignator
+  end
+  
+  #first message of the conversation.
+  def original_message
+    @original_message = self.mailboxer_messages.find(:first, :order => 'created_at') if @original_message.nil?
+    return @original_message
+  end
+  
+  #sender of the last message.
+  def last_sender
+    @last_sender = self.last_message.sender if @last_sender.nil?
+    return @last_sender
+  end
+  
+  #last message in the conversation.
+  def last_message
+    @last_message = self.mailboxer_messages.find(:first, :order => 'created_at DESC') if @last_message.nil?
+    return @last_message
+  end
+  
+  def mails(participant=nil)
+    return MailboxerMail.conversation(self).receiver(participant) if participant
+    return MailboxerMail.conversation(self)
+  end
+  
+  #all users involved in the conversation.
+  def recipients
+    return last_message.get_recipients
+  end
+  
+  def get_recipients
+    return self.recipients
+  end
+  
+  def count_messages
+    return MailboxerMessage.conversation(self).count
+  end
+  
+  protected
+  #[empty method]
+  #
+  #this gets called before_create. Implement this if you wish to clean out illegal content such as scripts or anything that will break layout. This is left empty because what is considered illegal content varies.
+  def clean
+    return if subject.nil?
+    #strip all illegal content here. (scripts, shit that will break layout, etc.)
+  end
+end

data/app/models/mailboxer_mail.rb

@@ -0,0 +1,70 @@
+class MailboxerMail < ActiveRecord::Base
+  belongs_to :mailboxer_message
+  has_one :mailboxer_conversation, :through => :mailboxer_message
+  belongs_to :receiver, :polymorphic => :true
+  scope :receiver, lambda { |receiver|
+    where(:receiver_id => receiver.id,:receiver_type => receiver.class.to_s)
+  }
+  scope :message, lambda { |message|
+    where(:mailboxer_message_id => message.id)
+  }
+  scope :conversation, lambda { |conversation|    
+    joins(:mailboxer_message).where('mailboxer_messages.mailboxer_conversation_id' => conversation.id)
+  }
+  scope :sentbox, where(:mailbox_type => "sentbox")
+  scope :inbox, where(:mailbox_type => "inbox")
+  scope :trash, where(:trashed => true)
+  scope :read, where(:read => true)
+  scope :unread, where(:read => false)
+  
+  class << self 
+    def mark_as_read(options={})    
+      where(options).update_all(:read => true)
+    end
+    
+    def mark_as_unread(options={}) 
+      where(options).update_all(:read => false)
+    end
+    
+    def move_to_trash(options={})     
+      where(options).update_all(:trashed => true)
+    end
+    
+    def untrash(options={})     
+      where(options).update_all(:trashed => false)
+    end
+    
+    def move_to_inbox(options={})     
+      where(options).update_all(:mailbox_type => :inbox, :trashed => false)
+    end
+    
+    def move_to_sentbox(options={})     
+      where(options).update_all(:mailbox_type => :sentbox, :trashed => false)
+    end
+  end 
+  
+  def mark_as_read 
+    update_attributes(:read => true)
+  end
+
+  def mark_as_unread
+    update_attributes(:read => false)
+  end
+  
+  def move_to_trash
+    update_attributes(:trashed => true)
+  end
+  
+  def untrash
+    update_attributes(:trashed => false)
+  end
+  
+  def move_to_inbox
+    update_attributes(:mailbox_type => :inbox, :trashed => false)
+  end
+  
+  def move_to_sentbox
+    update_attributes(:mailbox_type => :sentbox, :trashed => false)
+  end
+  
+end

data/app/models/mailboxer_mailbox.rb

@@ -0,0 +1,68 @@
+class MailboxerMailbox
+  #this is used to filter mail by mailbox type, use the [] method rather than setting this directly.
+  attr_accessor :type
+  #the user/owner of this mailbox, set when initialized.
+  attr_reader :messageable
+  #creates a new Mailbox instance with the given user and optional type.
+    
+  def initialize(recipient, box = :all)
+    @messageable = recipient
+    @type = box
+  end
+  #sets the mailbox type to the symbol corresponding to the given val.
+  def type=(val)
+    @type = val.to_sym
+  end
+
+  def conversations(options = {})
+    return MailboxerConversation.where(options).participant(@messageable)
+  end
+
+  def mail(options = {})
+    return MailboxerMail.where(options).receiver(@messageable)
+  end
+  
+  def inbox(options = {})
+    return self.mail(options).inbox
+  end
+  
+  def sentbox(options = {})
+    return self.mail(options).sentbox
+  end
+  
+  def trash(options = {})
+    return self.mail(options).trash
+  end
+
+  def [](mailbox_type)
+    self.type = mailbox_type
+    return self
+  end
+
+  def <<(msg)
+    return self.add(msg)
+  end
+
+  def add(msg)
+    mail_msg = MailboxerMail.new
+    mail_msg.mailboxer_message = msg
+    mail_msg.read = (msg.sender.id == @messageable.id && msg.sender.class == @messageable.class)
+    mail_msg.receiver = @messageable
+    mail_msg.mailbox_type = @type.to_s unless @type == :all
+    @messageable.mailboxer_mails << mail_msg
+    return mail_msg
+  end
+
+  def empty_trash(options = {})
+    return self.trash(options).delete_all
+  end
+
+  def has_conversation?(conversation)
+    return self.mail.conversation(converstaion).count!=0
+  end
+
+  def is_trashed?(conversation)
+    return self.trash.conversation(conversation).count!=0
+  end
+
+end

data/app/models/mailboxer_message.rb

@@ -0,0 +1,42 @@
+class MailboxerMessage < ActiveRecord::Base
+  #any additional info that needs to be sent in a message (ex. I use these to determine request types)
+  serialize :headers
+  
+  attr_accessor :recipients
+  
+  class_inheritable_accessor :on_deliver_callback
+  protected :on_deliver_callback  
+  class_inheritable_accessor :on_deliver_clean
+  protected :on_deliver_clean
+  belongs_to :sender, :polymorphic => :true
+  belongs_to :mailboxer_conversation
+  has_many :mailboxer_mails
+  scope :conversation, lambda { |conversation|    
+    where(:mailboxer_conversation_id => conversation.id)
+  }
+    
+  class << self
+    def on_deliver(clean_method, callback_method)
+      self.on_deliver_clean = clean_method
+      self.on_deliver_callback = callback_method
+    end
+  end  
+  
+  def deliver(mailbox_type, should_clean = true)
+    self.on_deliver_clean.call(self) unless self.on_deliver_clean.nil? or !should_clean
+    self.save
+    self.recipients.each do |r|
+      r.mailbox[mailbox_type] << self
+    end
+    self.on_deliver_callback.call(self, mailbox_type) unless self.on_deliver_callback.nil?
+  end
+  
+  def get_recipients
+    recipients_array = Array.new 
+    self.mailboxer_mails.each do |mail|      
+      recipients_array << mail.receiver
+    end
+    return recipients_array
+  end
+  
+end

data/lib/generators/mailboxer/install_generator.rb

@@ -0,0 +1,15 @@
+class Mailboxer::InstallGenerator < Rails::Generators::Base #:nodoc:
+  include Rails::Generators::Migration
+  
+  source_root File.expand_path('../templates', __FILE__)
+  
+  require 'rails/generators/active_record'
+  
+  def self.next_migration_number(dirname)
+    ActiveRecord::Generators::Base.next_migration_number(dirname)
+  end
+  
+  def create_migration_file
+    migration_template 'migration.rb', 'db/migrate/create_mailboxer.rb'
+  end
+end

data/lib/generators/mailboxer/templates/migration.rb

@@ -0,0 +1,31 @@
+class CreateMailboxer < ActiveRecord::Migration
+  def self.up    
+    create_table :mailboxer_conversations do |t|
+      t.column :subject, :string, :default => ""
+      t.column :created_at, :datetime, :null => false
+    end    
+    create_table :mailboxer_mails do |t|
+      t.references :receiver, :polymorphic => true
+      t.column :mailboxer_message_id, :integer, :null => false
+      t.column :read, :boolean, :default => false
+      t.column :trashed, :boolean, :default => false
+      t.column :mailbox_type, :string, :limit => 25
+      t.column :created_at, :datetime, :null => false
+    end    
+    create_table :mailboxer_messages do |t|
+      t.column :body, :text
+      t.column :subject, :string, :default => ""
+      t.column :headers, :text
+      t.references :sender, :polymorphic => true
+      t.column :mailboxer_conversation_id, :integer
+      t.column :sent, :boolean, :default => false
+      t.column :created_at, :datetime, :null => false
+    end    
+  end
+  
+  def self.down
+    drop_table :mailboxer_mails
+    drop_table :mailboxer_conversations
+    drop_table :mailboxer_messages
+  end
+end

data/lib/mailboxer.rb

@@ -0,0 +1,8 @@
+module Mailboxer 
+  module Models
+    autoload :Messageable, 'mailboxer/models/messageable'
+  end  
+end
+# reopen ActiveRecord and include all the above to make
+# them available to all our models if they want it
+require 'mailboxer/engine' 

data/lib/mailboxer/engine.rb

@@ -0,0 +1,10 @@
+module Mailboxer
+  class Engine < Rails::Engine
+    
+    initializer "mailboxer.models.messageable" do
+      ActiveSupport.on_load(:active_record) do
+        include Mailboxer::Models::Messageable
+      end
+    end
+  end
+end

data/lib/mailboxer/models/messageable.rb

@@ -0,0 +1,204 @@
+module Mailboxer 
+  module Models 
+    module Messageable       
+      extend ActiveSupport::Concern
+      
+      included do
+        has_many :mailboxer_messages
+        cattr_accessor :mailbox_types
+        has_many :mailboxer_mails, :order => 'created_at DESC', :dependent => :delete_all       
+        
+      end
+      # declare the class level helper methods which
+      # will load the relevant instance methods
+      # defined below when invoked
+      module ClassMethods
+        #enables a class to send and receive messages to members of the same class - currently assumes the model is of class type 'User', 
+        #some modifications to the migrations and model classes will need to be made to use a model of different type
+        #
+        #====options:
+        #* :received - the mailbox type to store received messages (defaults to :inbox)
+        #
+        #* :sent - the mailbox type to store sent messages (defaults to :sentbox)
+        #
+        #* :deleted - the mailbox type to store deleted messages (defaults to :trash)
+        #
+        #====example:
+        #   acts_as_messageable :received => :in, :sent => :sent, :deleted => :garbage
+        def acts_as_messageable
+          include Mailboxer::Models::Messageable::InstanceMethods
+        end
+      end
+      
+      #Adds class methods
+      #module SingletonMethods
+      #end
+      
+      # Adds instance methods.
+      module InstanceMethods
+        #returns an instance of class type Mailbox - this object essentially wraps the user's mail messages and provides a clean interface for accessing them. 
+        #see Mailbox for more details.
+        #
+        #====example:
+        #   phil = User.find(3123)
+        #   phil.mailbox[:inbox].unread_mail      #returns all unread mail in your inbox
+        #   phil.mailbox[:sentbox].mail         #returns all sent mail messages
+        #  
+        def mailbox
+          @mailbox = MailboxerMailbox.new(self) if @mailbox.nil?
+          @mailbox.type = :all
+          return @mailbox
+        end
+        #creates new Message and Conversation objects from the given parameters and delivers Mail to each of the recipients' inbox.
+        #
+        #====params:
+        #recipients::
+        #     a single user object or array of users to deliver the message to.
+        #msg_body::
+        #     the body of the message.
+        #subject::
+        #     the subject of the message, defaults to empty string if not provided.
+        #====returns:
+        #the sent Mail.
+        #
+        #====example:
+        #   phil = User.find(3123)
+        #   todd = User.find(4141)
+        #   phil.send_message(todd, 'whats up for tonight?', 'hey guy')      #sends a Mail message to todd's inbox, and a Mail message to phil's sentbox
+        #  
+        def send_message(recipients, msg_body, subject = '')
+          convo = MailboxerConversation.create({:subject => subject})
+          message = MailboxerMessage.create({:sender => self, :mailboxer_conversation => convo,  :body => msg_body, :subject => subject})
+          message.recipients = recipients.is_a?(Array) ? recipients : [recipients]
+          message.deliver(:inbox)
+          return mailbox[:sentbox] << message
+        end
+        #creates a new Message associated with the given conversation and delivers the reply to each of the given recipients.
+        #
+        #*explicitly calling this method is rare unless you are replying to a subset of the users involved in the conversation or 
+        #if you are including someone that is not currently in the conversation. 
+        #reply_to_sender, reply_to_all, and reply_to_conversation will suffice in most cases.
+        #
+        #====params:
+        #conversation::
+        #     the Conversation object that the mail you are responding to belongs.
+        #recipients::
+        #     a single User object or array of Users to deliver the reply message to.
+        #reply_body::
+        #     the body of the reply message.
+        #subject::
+        #     the subject of the message, defaults to 'RE: [original subject]' if one isnt given.
+        #====returns:
+        #the sent Mail.
+        #
+        def reply(conversation, recipients, reply_body, subject = nil)
+          return nil if(reply_body.blank?)
+          subject = subject || "RE: #{conversation.subject}"
+          response = MailboxerMessage.create({:sender => self, :mailboxer_conversation => conversation, :body => reply_body, :subject => subject})
+          response.recipients = recipients.is_a?(Array) ? recipients : [recipients]
+          response.deliver(:inbox)
+          return mailbox[:sentbox] << response
+        end
+        #sends a Mail to the sender of the given mail message.
+        #
+        #====params:
+        #mail::
+        #     the Mail object that you are replying to.
+        #reply_body::
+        #     the body of the reply message.
+        #subject::
+        #     the subject of the message, defaults to 'RE: [original subject]' if one isnt given.
+        #====returns:
+        #the sent Mail.
+        #
+        def reply_to_sender(mail, reply_body, subject = nil)
+          return reply(mail.mailboxer_conversation, mail.mailboxer_message.sender, reply_body, subject)
+        end
+        #sends a Mail to all of the recipients of the given mail message (excluding yourself).
+        #
+        #====params:
+        #mail::
+        #     the Mail object that you are replying to.
+        #reply_body::
+        #     the body of the reply message.
+        #subject::
+        #     the subject of the message, defaults to 'RE: [original subject]' if one isnt given.
+        #====returns:
+        #the sent Mail.
+        #
+        def reply_to_all(mail, reply_body, subject = nil)
+          msg = mail.mailboxer_message
+          recipients = msg.get_recipients
+          if(msg.sender != self)
+            recipients.delete(self)
+            if(!recipients.include?(msg.sender))
+              recipients << msg.sender
+            end
+          end
+          return reply(mail.mailboxer_conversation, recipients, reply_body, subject)
+        end
+        #sends a Mail to all users involved in the given conversation (excluding yourself).
+        #
+        #*this may have undesired effects if users have been added to the conversation after it has begun.
+        #
+        #====params:
+        #conversation::
+        #     the Conversation object that the mail you are responding to belongs.
+        #reply_body::
+        #     the body of the reply message.
+        #subject::
+        #     the subject of the message, defaults to 'RE: [original subject]' if one isnt given.
+        #====returns:
+        #the sent Mail.
+        #
+        def reply_to_conversation(conversation, reply_body, subject = nil)
+          #move conversation to inbox if it is currently in the trash - doesnt make much sense replying to a trashed convo.
+          if(mailbox.is_trashed?(conversation))
+            mailbox.mail.conversation(conversation).untrash
+          end
+          #remove self from recipients unless you are the originator of the convo
+          recipients = conversation.get_recipients
+          if(conversation.originator != self)
+            recipients.delete(self)
+            if(!recipients.include?(conversation.originator))
+              recipients << conversation.originator
+            end
+          end
+          return reply(conversation,recipients, reply_body, subject)
+        end
+        #returns the mail given as the parameter, marked as read.
+        def read_mail(mail)          
+            return mail.mark_as_read if mail.receiver == self
+        end
+        #returns the mail given as the parameter, marked as unread.
+        def unread_mail(mail)
+            return mail.mark_as_unread if mail.receiver == self
+        end
+        #returns an array of the user's Mail associated with the given conversation. 
+        #All mail is marked as read but the returning array is built before this so you can see which messages were unread when viewing the conversation.
+        #
+        #???This returns deleted/trashed messages as well for the purpose of reading trashed convos, to disable this send the option ':conditions => "mail.trashed != true"'
+        #
+        #====params:
+        #conversation::
+        #     the Conversation object that you want to read.
+        #options::
+        #     any options to filter the conversation, these are used as find options so all valid options for find will work.
+        #
+        #====returns:
+        #array of Mail belonging to the given conversation.
+        #
+        def read_conversation(conversation, options = {})
+          mails = conversation.mailboxer_mails.receiver(self)
+          mails_clone = mails.clone
+          
+          mails.each do |mail|
+            mail.mark_as_read
+          end
+          
+          return mails_clone
+        end
+      end
+    end
+  end
+end