gmail 0.3.0

data/lib/gmail/client.rb

@@ -0,0 +1,221 @@
+module Gmail
+  class Client
+    # Raised when connection with GMail IMAP service couldn't be established. 
+    class ConnectionError < SocketError; end
+    # Raised when given username or password are invalid.
+    class AuthorizationError < Net::IMAP::NoResponseError; end
+    # Raised when delivered email is invalid. 
+    class DeliveryError < ArgumentError; end
+  
+    # GMail IMAP defaults
+    GMAIL_IMAP_HOST = 'imap.gmail.com'
+    GMAIL_IMAP_PORT = 993
+    
+    # GMail SMTP defaults
+    GMAIL_SMTP_HOST = "smtp.gmail.com"
+    GMAIL_SMTP_PORT = 587
+  
+    attr_reader :username
+    attr_reader :password
+    attr_reader :options
+  
+    def initialize(username, password, options={})
+      defaults  = {}
+      @username = fill_username(username)
+      @password = password
+      @options  = defaults.merge(options)
+    end
+    
+    # Connect to gmail service. 
+    def connect(raise_errors=false)
+      @imap = Net::IMAP.new(GMAIL_IMAP_HOST, GMAIL_IMAP_PORT, true, nil, false)
+    rescue SocketError
+      raise_errors and raise ConnectionError, "Couldn't establish connection with GMail IMAP service"
+    end
+    
+    # This version of connect will raise error on failure...
+    def connect!
+      connect(true)
+    end
+    
+    # Return current connection. Log in automaticaly to specified account if 
+    # it is necessary.
+    def connection
+      login and at_exit { logout } unless logged_in?
+      @imap
+    end
+    alias :conn :connection
+    
+    # Login to specified account.
+    def login(raise_errors=false)
+      @imap and @logged_in = (login = @imap.login(username, password)) && login.name == 'OK'
+    rescue Net::IMAP::NoResponseError
+      raise_errors and raise AuthorizationError, "Couldn't login to given GMail account: #{username}"
+    end
+    alias :sign_in :login
+    
+    # This version of login will raise error on failure...
+    def login!
+      login(true)
+    end
+    alias :sign_in! :login!
+    
+    # Returns +true+ when you are logged in to specified account.
+    def logged_in?
+      !!@logged_in
+    end
+    alias :signed_in? :logged_in?
+    
+    # Logout from GMail service. 
+    def logout
+      @imap && logged_in? and @imap.logout
+    ensure
+      @logged_in = false
+    end
+    alias :sign_out :logout
+    
+    # Return labels object, which helps you with managing your GMail labels.
+    # See <tt>Gmail::Labels</tt> for details.
+    def labels
+      @labels ||= Labels.new(conn)
+    end
+    
+    # Compose new e-mail.
+    #
+    # ==== Examples
+    #   
+    #   mail = gmail.compose
+    #   mail.from "test@gmail.org"
+    #   mail.to "friend@gmail.com"
+    #
+    # ... or block style:
+    #  
+    #   mail = gmail.compose do 
+    #     from "test@gmail.org"
+    #     to "friend@gmail.com"
+    #     subject "Hello!"
+    #     body "Hello my friend! long time..."
+    #   end
+    #
+    # Now you can deliver your mail:
+    #
+    #   gmail.deliver(mail)
+    def compose(mail=nil, &block)
+      if block_given?
+        mail = Mail.new(&block)
+      elsif !mail 
+        mail = Mail.new
+      end 
+      mail.delivery_method(*smtp_settings)
+      mail.from = username unless mail.from
+      mail
+    end
+    alias :message :compose
+    
+    # Compose (optionaly) and send given email. 
+    #
+    # ==== Examples
+    #
+    #   gmail.deliver do 
+    #     to "friend@gmail.com"
+    #     subject "Hello friend!"
+    #     body "Hi! How are you?"
+    #   end
+    #
+    # ... or with already created message:
+    #
+    #   mail = Mail.new { ... }
+    #   gmail.deliver(mail)
+    #
+    #   mail = gmail.compose { ... }
+    #   gmail.deliver(mail)
+    def deliver(mail=nil, raise_errors=false, &block)
+      mail = compose(mail, &block) if block_given?
+      mail.deliver!
+    rescue Object => ex
+      raise_errors and raise DeliveryError, "Couldn't deliver email: #{ex.to_s}"
+    end
+    
+    # This version of deliver will raise error on failure...
+    def deliver!(mail=nil, &block)
+      deliver(mail, true, &block)
+    end
+    
+    # Do something with given mailbox or within it context. 
+    #
+    # ==== Examples
+    #
+    #   mailbox = gmail.mailbox("INBOX")
+    #   mailbox.emails(:all)
+    #   mailbox.count(:unread, :before => Time.now-(20*24*3600))
+    #
+    # ... or block style:
+    #
+    #   gmail.label("Work") do |mailbox|
+    #     mailbox.emails(:unread)
+    #     mailbox.count(:all)
+    #     ...
+    #   end
+    def mailbox(name, &block)
+      name = name.to_s
+      mailbox = (mailboxes[name] ||= Mailbox.new(self, name))
+      switch_to_mailbox(name) if @current_mailbox != name
+      if block_given?
+        mailbox_stack << @current_mailbox
+        result = block.arity == 1 ? block.call(mailbox) : block.call
+        mailbox_stack.pop
+        switch_to_mailbox(mailbox_stack.last)
+        return result
+      end
+      mailbox
+    end
+    alias :in_mailbox :mailbox
+    alias :in_label :mailbox
+    alias :label :mailbox
+    
+    # Alias for <tt>mailbox("INBOX")</tt>. See <tt>Gmail::Client#mailbox</tt>
+    # for details.
+    def inbox
+      mailbox("INBOX")
+    end
+    
+    def mailboxes
+      @mailboxes ||= {}
+    end
+    
+    def inspect
+      "#<Gmail::Client#{'0x%04x' % (object_id << 1)} (#{username}) #{'dis' if !logged_in?}connected>"
+    end
+    
+    def fill_username(username)
+      username =~ /@/ ? username : "#{username}@gmail.com"
+    end
+
+    def mail_domain
+      username.split('@')[0]
+    end
+    
+    private
+    
+    def switch_to_mailbox(mailbox)
+      conn.select(mailbox) if mailbox
+      @current_mailbox = mailbox
+    end
+    
+    def mailbox_stack
+      @mailbox_stack ||= []
+    end
+    
+    def smtp_settings
+      [:smtp, {
+        :address => GMAIL_SMTP_HOST,
+        :port => GMAIL_SMTP_PORT,
+        :domain => mail_domain,
+        :user_name => username,
+        :password => password,
+        :authentication => 'plain',
+        :enable_starttls_auto => true
+      }]
+    end
+  end # Client
+end # Gmail

data/lib/gmail/labels.rb

@@ -0,0 +1,42 @@
+module Gmail
+  class Labels
+    attr_reader :connection
+    alias :conn :connection
+     
+    def initialize(connection)
+      @connection = connection
+    end
+    
+    # Get list of all defined labels.
+    def all
+      (conn.list("", "%")+conn.list("[Gmail]/", "%")).inject([]) do |labels,label|
+        label[:name].each_line {|l| labels << l }
+        labels 
+      end
+    end
+    alias :list :all
+    
+    # Returns +true+ when given label defined. 
+    def exists?(label)
+      all.include?(label)
+    end
+    alias :exist? :exists?
+    
+    # Creates given label in your account.
+    def create(label)
+      !!conn.create(label) rescue false
+    end
+    alias :new :create
+    alias :add :create
+    
+    # Deletes given label from your account. 
+    def delete(label)
+      !!conn.delete(label) rescue false
+    end
+    alias :remove :delete
+    
+    def inspect
+      "#<Gmail::Labels#{'0x%04x' % (object_id << 1)}>"
+    end
+  end # Labels
+end # Gmail

data/lib/gmail/mailbox.rb

@@ -0,0 +1,92 @@
+module Gmail
+  class Mailbox
+    MAILBOX_ALIASES = {
+      :all    => ['ALL'],
+      :unread => ['UNSEEN'],
+      :read   => ['SEEN']
+    }
+  
+    attr_reader :name
+
+    def initialize(gmail, name="INBOX")
+      @name  = name
+      @gmail = gmail
+    end
+
+    # Returns list of emails which meets given criteria. 
+    #
+    # ==== Examples
+    #
+    #   gmail.inbox.emails(:all)
+    #   gmail.inbox.emails(:unread, :from => "friend@gmail.com")
+    #   gmail.inbox.emails(:all, :after => Time.now-(20*24*3600))
+    #   gmail.mailbox("Test").emails(:read)
+    #
+    #   gmail.mailbox("Test") do |box| 
+    #     box.emails(:read)
+    #     box.emails(:unread) do |email|
+    #       ... do something with each email...
+    #     end
+    #   end
+    def emails(*args, &block)
+      args << :all if args.size == 0
+
+      if args.first.is_a?(Symbol) 
+        search = MAILBOX_ALIASES[args.shift]
+        opts = args.first.is_a?(Hash) ? args.first : {}
+        
+        opts[:after]      and search.concat ['SINCE', opts[:after].to_imap_date]
+        opts[:before]     and search.concat ['BEFORE', opts[:before].to_imap_date]
+        opts[:on]         and search.concat ['ON', opts[:on].to_imap_date]
+        opts[:from]       and search.concat ['FROM', opts[:from]]
+        opts[:to]         and search.concat ['TO', opts[:to]]
+        opts[:subject]    and search.concat ['SUBJECT', opts[:subject]]
+        opts[:label]      and search.concat ['LABEL', opts[:label]]
+        opts[:attachment] and search.concat ['HAS', 'attachment']
+        opts[:search]     and search.concat [opts[:search]]
+        
+        @gmail.mailbox(name) do
+          @gmail.conn.uid_search(search).collect do |uid| 
+            message = (messages[uid] ||= Message.new(self, uid))
+            block.call(message) if block_given?
+            message
+          end
+        end
+      elsif args.first.is_a?(Hash)
+        emails(:all, args.first)
+      else
+        raise ArgumentError, "Invalid search criteria"
+      end
+    end
+    alias :mails :emails
+    alias :search :emails
+    alias :find :emails
+    alias :filter :emails
+
+    # This is a convenience method that really probably shouldn't need to exist, 
+    # but it does make code more readable, if seriously all you want is the count 
+    # of messages.
+    #
+    # ==== Examples
+    #
+    #   gmail.inbox.count(:all)
+    #   gmail.inbox.count(:unread, :from => "friend@gmail.com")
+    #   gmail.mailbox("Test").count(:all, :after => Time.now-(20*24*3600))
+    def count(*args)
+      emails(*args).size
+    end
+
+    # Cached messages. 
+    def messages
+      @messages ||= {}
+    end
+    
+    def inspect
+      "#<Gmail::Mailbox#{'0x%04x' % (object_id << 1)} name=#{@name}>"
+    end
+
+    def to_s
+      name
+    end
+  end # Message
+end # Gmail

data/lib/gmail/message.rb

@@ -0,0 +1,137 @@
+require 'mime/message'
+
+module Gmail
+  class Message
+    # Raised when given label doesn't exists.
+    class NoLabelError < Exception; end 
+  
+    attr_reader :uid
+    
+    def initialize(mailbox, uid)
+      @uid     = uid
+      @mailbox = mailbox
+      @gmail   = mailbox.instance_variable_get("@gmail") if mailbox
+    end
+    
+    def uid
+      @uid ||= @gmail.conn.uid_search(['HEADER', 'Message-ID', message_id])[0]
+    end
+    
+    # Mark message with given flag.
+    def flag(name)
+      !!@gmail.mailbox(@mailbox.name) { @gmail.conn.uid_store(uid, "+FLAGS", [name]) }
+    end
+    
+    # Unmark message. 
+    def unflag(name)
+      !!@gmail.mailbox(@mailbox.name) { @gmail.conn.uid_store(uid, "-FLAGS", [name]) }
+    end
+    
+    # Do commonly used operations on message. 
+    def mark(flag)
+      case flag
+        when :read    then read!
+        when :unread  then unread!
+        when :deleted then delete!
+        when :spam    then spam!
+      else
+        flag(flag)
+      end
+    end
+    
+    # Mark this message as a spam.
+    def spam!
+      move_to('[Gmail]/Spam')
+    end
+    
+    # Mark as read.
+    def read!
+      flag(:Seen)
+    end
+    
+    # Mark as unread.
+    def unread!
+      unflag(:Seen)
+    end
+    
+    # Mark message with star.
+    def star!
+      flag('[Gmail]/Starred')
+    end
+    
+    # Remove message from list of starred.
+    def unstar!
+      unflag('[Gmail]/Starred')
+    end
+    
+    # Move to trash.
+    def delete!
+      @mailbox.messages.delete(uid)
+      flag(:Deleted)
+    end
+
+    # Archive this message.
+    def archive!
+      move_to('[Gmail]/All Mail')
+    end
+    
+    # Move to given box and delete from others.  
+    def move_to(name, from=nil)
+      label(name, from) && delete!
+    end
+    alias :move :move_to
+    
+    # Move message to given and delete from others. When given mailbox doesn't 
+    # exist then it will be automaticaly created. 
+    def move_to!(name, from=nil)
+      label!(name, from) && delete!
+    end
+    alias :move! :move_to!
+    
+    # Mark this message with given label. When given label doesn't exist then
+    # it will raise <tt>NoLabelError</tt>. 
+    #
+    # See also <tt>Gmail::Message#label!</tt>.
+    def label(name, from=nil)
+      @gmail.mailbox(from || @mailbox.name) { @gmail.conn.uid_copy(uid, name) }
+    rescue Net::IMAP::NoResponseError
+      raise NoLabelError, "Label '#{name}' doesn't exist!"
+    end
+    alias :add_label :label
+
+    # Mark this message with given label. When given label doesn't exist then
+    # it will be automaticaly created. 
+    #
+    # See also <tt>Gmail::Message#label</tt>.
+    def label!(name, from=nil)
+      label(name, from) 
+    rescue NoLabelError
+      @gmail.labels.add(name)
+      label!(name, from)
+    end
+    alias :add_label! :add_label
+    
+    # Remove given label from this message. 
+    def remove_label!(name)
+      move_to('[Gmail]/All Mail', name)
+    end
+    alias :delete_label! :remove_label!
+    
+    def inspect
+      "#<Gmail::Message#{'0x%04x' % (object_id << 1)} mailbox=#{@mailbox.name}#{' uid='+@uid.to_s if @uid}#{' message_id='+@message_id.to_s if @message_id}>"
+    end
+    
+    def method_missing(meth, *args, &block)
+      # Delegate rest directly to the message.  
+      message.send(meth, *args, &block)
+    end
+    
+    private
+    
+    def message
+      @message ||= Mail.new(@gmail.mailbox(@mailbox.name) { 
+        @gmail.conn.uid_fetch(uid, "RFC822")[0].attr["RFC822"] 
+      })
+    end
+  end # Message
+end # Gmail