gmail 0.4.2 → 0.5.0

data/lib/gmail/client/xoauth2.rb

@@ -0,0 +1,39 @@
+require 'gmail_xoauth'
+
+module Gmail
+  module Client
+    class XOAuth2 < Base
+      attr_reader :token
+
+      def initialize(username, token)
+        @token = token
+
+        super(username, {})
+      end
+
+      def login(raise_errors = false)
+        @imap and @logged_in = (login = @imap.authenticate('XOAUTH2', username, token)) && login.name == 'OK'
+      rescue Net::IMAP::NoResponseError => e
+        if raise_errors
+          message = "Couldn't login to given Gmail account: #{username}"
+          message += " (#{e.response.data.text.strip})"
+          raise(AuthorizationError.new(e.response), message, e.backtrace)
+        end
+      end
+
+      def smtp_settings
+        [:smtp, {
+           :address => GMAIL_SMTP_HOST,
+           :port => GMAIL_SMTP_PORT,
+           :domain => mail_domain,
+           :user_name => username,
+           :password => token,
+           :authentication => :xoauth2,
+           :enable_starttls_auto => true
+         }]
+      end
+    end # XOAuth
+
+    register :xoauth2, XOAuth2
+  end # Client
+end # Gmail

data/lib/gmail/imap_extensions.rb

@@ -0,0 +1,150 @@
+module Gmail
+  module ImapExtensions
+    # Taken from https://github.com/oxos/gmail-oauth-thread-stats/blob/master/gmail_imap_extensions_compatibility.rb
+    def self.patch_net_imap_response_parser(klass = Net::IMAP::ResponseParser)
+      # https://github.com/ruby/ruby/blob/4d426fc2e03078d583d5d573d4863415c3e3eb8d/lib/net/imap.rb#L2258
+      klass.class_eval do
+        def msg_att(n = -1)
+          match(Net::IMAP::ResponseParser::T_LPAR)
+          attr = {}
+          while true
+            token = lookahead
+            case token.symbol
+            when Net::IMAP::ResponseParser::T_RPAR
+              shift_token
+              break
+            when Net::IMAP::ResponseParser::T_SPACE
+              shift_token
+              next
+            end
+            case token.value
+            when /\A(?:ENVELOPE)\z/ni
+              name, val = envelope_data
+            when /\A(?:FLAGS)\z/ni
+              name, val = flags_data
+            when /\A(?:INTERNALDATE)\z/ni
+              name, val = internaldate_data
+            when /\A(?:RFC822(?:\.HEADER|\.TEXT)?)\z/ni
+              name, val = rfc822_text
+            when /\A(?:RFC822\.SIZE)\z/ni
+              name, val = rfc822_size
+            when /\A(?:BODY(?:STRUCTURE)?)\z/ni
+              name, val = body_data
+            when /\A(?:UID)\z/ni
+              name, val = uid_data
+
+            # Gmail extension
+            # Cargo-cult code warning: no idea why the regexp works - just copying a pattern
+            when /\A(?:X-GM-LABELS)\z/ni
+              name, val = x_gm_labels_data
+            when /\A(?:X-GM-MSGID)\z/ni
+              name, val = uid_data
+            when /\A(?:X-GM-THRID)\z/ni
+              name, val = uid_data
+            # End Gmail extension
+
+            else
+              parse_error("unknown attribute `%s' for {%d}", token.value, n)
+            end
+            attr[name] = val
+          end
+          return attr
+        end
+
+        # Based on Net::IMAP#flags_data, but calling x_gm_labels_list to parse labels
+        def x_gm_labels_data
+          token = match(self.class::T_ATOM)
+          name = token.value.upcase
+          match(self.class::T_SPACE)
+          return name, x_gm_label_list
+        end
+
+        # Based on Net::IMAP#flag_list with a modified Regexp
+        # Labels are returned as escape-quoted strings
+        # We extract the labels using a regexp which extracts any unescaped strings
+        def x_gm_label_list
+          if @str.index(/\(([^)]*)\)/ni, @pos)
+            resp = extract_labels_response
+
+            # We need to manually update the position of the regexp to prevent trip-ups
+            @pos += resp.length
+
+            # `resp` will look something like this:
+            # ("\\Inbox" "\\Sent" "one's and two's" "some new label" Awesome Ni&APE-os)
+            return resp.gsub(/^\s*\(|\)\s*$/, '').scan(/"([^"]*)"|([^\s"]+)/ni).flatten.compact.collect(&:unescape)
+          else
+            parse_error("invalid label list")
+          end
+        end
+
+        # The way Gmail return tokens can cause issues with Net::IMAP's reader,
+        # so we need to extract this section manually
+        def extract_labels_response
+          special, quoted = false, false
+          index, paren_count = 0, 0
+
+          # Start parsing response string for the labels section, parentheses inclusive
+          labels_header = "X-GM-LABELS ("
+          start = @str.index(labels_header) + labels_header.length - 1
+          substr = @str[start..-1]
+          substr.each_char do |char|
+            index += 1
+            case char
+            when '('
+              paren_count += 1 unless quoted
+            when ')'
+              paren_count -= 1 unless quoted
+              break if paren_count == 0
+            when '"'
+              quoted = !quoted unless special
+            end
+            special = (char == '\\' && !special)
+          end
+          substr[0..index]
+        end
+      end # class_eval
+
+      # Add String#unescape
+      add_unescape
+    end # PNIRP
+
+    def self.add_unescape(klass = String)
+      klass.class_eval do
+        # Add a method to string which unescapes special characters
+        # We use a simple state machine to ensure that specials are not
+        # themselves escaped
+        def unescape
+          unesc = ''
+          special = false
+          escapes = { '\\' => '\\',
+                      '"'  => '"',
+                      'n' => "\n",
+                      't' => "\t",
+                      'r' => "\r",
+                      'f' => "\f",
+                      'v' => "\v",
+                      '0' => "\0",
+                      'a' => "\a"
+                    }
+
+          self.each_char do |char|
+            if special
+              # If in special mode, add in the replaced special char if there's a match
+              # Otherwise, add in the backslash and the current character
+              unesc << (escapes.keys.include?(char) ? escapes[char] : "\\#{char}")
+              special = false
+            else
+              # Toggle special mode if backslash is detected; otherwise just add character
+              if char == '\\'
+                special = true
+              else
+                unesc << char
+              end
+            end
+          end
+          unesc
+        end
+      end
+    end
+  end
+end

data/lib/gmail/labels.rb

@@ -3,21 +3,21 @@ module Gmail
     include Enumerable
     attr_reader :connection
     alias :conn :connection
-     
+
     def initialize(connection)
       @connection = connection
     end
-    
+
     # Get list of all defined labels.
     def all
       @list = []
-      
+
       ## check each item in list for subfolders
-      conn.list("", "%").each {|l| sublabels_or_label(l)}
-      
-      @list.inject([]) do |labels,label|
-        label[:name].each_line {|l| labels << Net::IMAP.decode_utf7(l) }
-        labels 
+      conn.list("", "%").each { |l| sublabels_or_label(l) }
+
+      @list.inject([]) do |labels, label|
+        label[:name].each_line { |l| labels << Net::IMAP.decode_utf7(l) }
+        labels
       end
     end
     alias :list :all
@@ -28,35 +28,52 @@ module Gmail
         @list << label
       else
         @list << label
-        conn.list("#{label.name}/", "%").each {|l| sublabels_or_label(l)}
+        conn.list("#{label.name}/", "%").each { |l| sublabels_or_label(l) }
       end
     end
-    
+
     def each(*args, &block)
       all.each(*args, &block)
     end
-    
-    # Returns +true+ when given label defined. 
+
+    # 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(Net::IMAP.encode_utf7(label)) rescue false
     end
     alias :new :create
     alias :add :create
-    
-    # Deletes given label from your account. 
+
+    # Deletes given label from your account.
     def delete(label)
       !!conn.delete(Net::IMAP.encode_utf7(label)) rescue false
     end
     alias :remove :delete
-    
+
     def inspect
       "#<Gmail::Labels#{'0x%04x' % (object_id << 1)}>"
     end
+
+    # Localizes a specific label flag into a label name
+
+    # Accepts standard mailbox flags returned by LIST's special-use extension:
+    # :Inbox, :All, :Drafts, :Sent, :Trash, :Important, :Junk, :Flagged
+    # and their string equivalents. Capitalization agnostic.
+    def localize(label)
+      type = label.to_sym.capitalize
+      if [:All, :Drafts, :Sent, :Trash, :Important, :Junk, :Flagged].include? type
+        @mailboxes ||= connection.list("", "*")
+        @mailboxes.select { |box| box.attr.include? type }.collect(&:name).compact.uniq.first
+      elsif type == :Inbox
+        'INBOX'
+      else
+        label
+      end
+    end
   end # Labels
 end # Gmail

data/lib/gmail/mailbox.rb

@@ -9,44 +9,29 @@ module Gmail
       :flagged   => ['FLAGGED'],
       :unflagged => ['UNFLAGGED'],
       :starred   => ['FLAGGED'],
-      :unstarred => ['UNFLAGGED'], 
+      :unstarred => ['UNFLAGGED'],
       :deleted   => ['DELETED'],
       :undeleted => ['UNDELETED'],
       :draft     => ['DRAFT'],
       :undrafted => ['UNDRAFT']
     }
-  
+
     attr_reader :name
-    attr_reader :external_name
+    attr_reader :encoded_name
 
-    def initialize(gmail, name="INBOX")
-      @name  = name
-      @external_name = Net::IMAP.decode_utf7(name)
+    def initialize(gmail, name = "INBOX")
+      @name = Net::IMAP.decode_utf7(name)
+      @encoded_name = Net::IMAP.encode_utf7(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)
+    def fetch_uids(*args)
       args << :all if args.size == 0
 
-      if args.first.is_a?(Symbol) 
+      if args.first.is_a?(Symbol)
         search = MAILBOX_ALIASES[args.shift].dup
         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]
@@ -57,28 +42,66 @@ module Gmail
         opts[:attachment] and search.concat ['HAS', 'attachment']
         opts[:search]     and search.concat ['BODY', opts[:search]]
         opts[:body]       and search.concat ['BODY', opts[:body]]
+        opts[:uid]        and search.concat ['UID', opts[:uid]]
+        opts[:gm]         and search.concat ['X-GM-RAW', opts[:gm]]
         opts[:query]      and search.concat opts[:query]
 
-        @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
+        @gmail.mailbox(name) {
+          @gmail.conn.uid_search(search)
+        }
       elsif args.first.is_a?(Hash)
-        emails(:all, args.first)
+        fetch_uids(:all, args.first)
       else
         raise ArgumentError, "Invalid search criteria"
       end
     end
-    alias :mails :emails
+
+    # 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)
+      fetch_uids(*args).collect do |uid|
+        message = Message.new(self, uid)
+        yield(message) if block_given?
+        message
+      end
+    end
     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 
+    def emails_in_batches(*args, &block)
+      messages = Array.new
+
+      uids = fetch_uids(*args)
+      if uids && uids.any?
+        uids.each_slice(100) do |slice|
+          @gmail.conn.uid_fetch(slice, Message::PREFETCH_ATTRS).each do |data|
+            message = Message.new(self, nil, data)
+            yield(message) if block_given?
+            messages << message
+          end
+        end
+      end
+
+      messages
+    end
+    alias :search_in_batches :emails_in_batches
+    alias :find_in_batches :emails_in_batches
+
+    # 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
@@ -95,13 +118,8 @@ module Gmail
       @gmail.mailbox(name) { @gmail.conn.expunge }
     end
 
-    # Cached messages. 
-    def messages
-      @messages ||= {}
-    end
-    
     def inspect
-      "#<Gmail::Mailbox#{'0x%04x' % (object_id << 1)} name=#{external_name}>"
+      "#<Gmail::Mailbox#{'0x%04x' % (object_id << 1)} name=#{name}>"
     end
 
     def to_s

data/lib/gmail/message.rb

@@ -1,133 +1,167 @@
 module Gmail
   class Message
+    PREFETCH_ATTRS = ["UID", "ENVELOPE", "BODY.PEEK[]", "FLAGS", "X-GM-LABELS", "X-GM-MSGID", "X-GM-THRID"]
+
     # Raised when given label doesn't exists.
-    class NoLabelError < Exception; end 
-  
-    attr_reader :uid
-    
-    def initialize(mailbox, uid)
+    class NoLabelError < Exception; end
+
+    def initialize(mailbox, uid, _attrs = nil)
       @uid     = uid
       @mailbox = mailbox
-      @gmail   = mailbox.instance_variable_get("@gmail") if mailbox
-    end
-        
-    def labels
-      @gmail.conn.uid_fetch(uid, "X-GM-LABELS")[0].attr["X-GM-LABELS"]
+      @gmail   = mailbox.instance_variable_get("@gmail") if mailbox  # UGLY
+      @_attrs  = _attrs
     end
-   
+
     def uid
-      @uid ||= @gmail.conn.uid_search(['HEADER', 'Message-ID', message_id])[0]
+      @uid ||= fetch("UID")
+    end
+
+    def msg_id
+      @msg_id ||= fetch("X-GM-MSGID")
+    end
+    alias_method :message_id, :msg_id
+
+    def thr_id
+      @thr_id ||= fetch("X-GM-THRID")
+    end
+    alias_method :thread_id, :thr_id
+
+    def envelope
+      @envelope ||= fetch("ENVELOPE")
+    end
+
+    def message
+      @message ||= Mail.new(fetch("BODY[]"))
     end
-    
+    alias_method :raw_message, :message
+
+    def flags
+      @flags ||= fetch("FLAGS")
+    end
+
+    def labels
+      @labels ||= fetch("X-GM-LABELS")
+    end
+
     # Mark message with given flag.
     def flag(name)
-      !!@gmail.mailbox(@mailbox.name) { @gmail.conn.uid_store(uid, "+FLAGS", [name]) }
+      !!@gmail.mailbox(@mailbox.name) do
+        @gmail.conn.uid_store(uid, "+FLAGS", [name])
+        clear_cached_attributes
+      end
     end
-    
-    # Unmark message. 
+
+    # Unmark message.
     def unflag(name)
-      !!@gmail.mailbox(@mailbox.name) { @gmail.conn.uid_store(uid, "-FLAGS", [name]) }
+      !!@gmail.mailbox(@mailbox.name) do
+        @gmail.conn.uid_store(uid, "-FLAGS", [name])
+        clear_cached_attributes
+      end
     end
-    
-    # Do commonly used operations on message. 
+
+    # 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!
+      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')
+
+    # Check whether message is read
+    def read?
+      flags.include?(:Seen)
     end
-    
+
     # Mark as read.
     def read!
       flag(:Seen)
     end
-    
+
     # Mark as unread.
     def unread!
       unflag(:Seen)
     end
-    
+
+    # Check whether message is starred
+    def starred?
+      flags.include?(:Flagged)
+    end
+
     # Mark message with star.
     def star!
-      flag('[Gmail]/Starred')
+      flag(:Flagged)
     end
-    
+
     # Remove message from list of starred.
     def unstar!
-      unflag('[Gmail]/Starred')
+      unflag(:Flagged)
     end
-    
-    # Move to trash / bin.
-    def delete!
-      @mailbox.messages.delete(uid)
-      flag(:deleted)
 
-      # For some, it's called "Trash", for others, it's called "Bin". Support both.
-      trash =  @gmail.labels.exist?('[Gmail]/Bin') ? '[Gmail]/Bin' : '[Gmail]/Trash'
-      move_to(trash) unless %w[[Gmail]/Spam [Gmail]/Bin [Gmail]/Trash].include?(@mailbox.name)
+    # Marking as spam is done by adding the `\Spam` label. To undo this,
+    # you just re-apply the `\Inbox` label (see `#unspam!`)
+    def spam!
+      add_label("\\Spam")
     end
 
-    # Archive this message.
+    # Deleting is done by adding the `\Trash` label. To undo this,
+    # you just re-apply the `\Inbox` label (see `#undelete!`)
+    def delete!
+      add_label("\\Trash")
+    end
+
+    # Archiving is done by adding the `\Trash` label. To undo this,
+    # you just re-apply the `\Inbox` label (see `#unarchive!`)
     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! if !%w[[Gmail]/Bin [Gmail]/Trash].include?(name)
-    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(Net::IMAP.encode_utf7(from || @mailbox.external_name)) { @gmail.conn.uid_copy(uid, Net::IMAP.encode_utf7(name)) }
-    rescue Net::IMAP::NoResponseError
-      raise NoLabelError, "Label '#{name}' doesn't exist!"
-    end
-
-    # 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(Net::IMAP.encode_utf7(name))
-      label(name, from)
-    end
-    alias :add_label :label!
-    alias :add_label! :label!
-    
-    # Remove given label from this message. 
-    def remove_label!(name)
-      move_to('[Gmail]/All Mail', name)
-    end
-    alias :delete_label! :remove_label!
-    
+      remove_label("\\Inbox")
+    end
+
+    def unarchive!
+      add_label("\\Inbox")
+    end
+    alias_method :unspam!, :unarchive!
+    alias_method :undelete!, :unarchive!
+
+    # Move to given box and delete from others.
+    # Apply a given label and optionally remove one.
+    # TODO: We should probably deprecate this method. It doesn't really add a lot
+    #       of value, especially since the concept of "moving" a message from one
+    #       label to another doesn't totally make sense in the Gmail world.
+    def move_to(name, from = nil)
+      add_label(name)
+      remove_label(from) if from
+    end
+    alias_method :move, :move_to
+    alias_method :move!, :move_to
+    alias_method :move_to!, :move_to
+
+    # Use Gmail IMAP Extensions to add a Label to an email
+    def add_label(name)
+      @gmail.mailbox(@mailbox.name) do
+        @gmail.conn.uid_store(uid, "+X-GM-LABELS", [Net::IMAP.encode_utf7(name.to_s)])
+        clear_cached_attributes
+      end
+    end
+    alias_method :label, :add_label
+    alias_method :label!, :add_label
+    alias_method :add_label!, :add_label
+
+    # Use Gmail IMAP Extensions to remove a Label from an email
+    def remove_label(name)
+      @gmail.mailbox(@mailbox.name) do
+        @gmail.conn.uid_store(uid, "-X-GM-LABELS", [Net::IMAP.encode_utf7(name.to_s)])
+        clear_cached_attributes
+      end
+    end
+    alias_method :remove_label!, :remove_label
+
     def inspect
-      "#<Gmail::Message#{'0x%04x' % (object_id << 1)} mailbox=#{@mailbox.external_name}#{' uid='+@uid.to_s if @uid}#{' message_id='+@message_id.to_s if @message_id}>"
+      "#<Gmail::Message#{'0x%04x' % (object_id << 1)} mailbox=#{@mailbox.name}#{' uid=' + @uid.to_s if @uid}#{' message_id=' + @msg_id.to_s if @msg_id}>"
     end
-    
+
     def method_missing(meth, *args, &block)
       # Delegate rest directly to the message.
       if envelope.respond_to?(meth)
@@ -149,18 +183,25 @@ module Gmail
       end
     end
 
-    def envelope
-      @envelope ||= @gmail.mailbox(@mailbox.name) {
-        @gmail.conn.uid_fetch(uid, "ENVELOPE")[0].attr["ENVELOPE"]
-      }
-    end
-    
-    def message
-      @message ||= Mail.new(@gmail.mailbox(@mailbox.name) { 
-        @gmail.conn.uid_fetch(uid, "RFC822")[0].attr["RFC822"] # RFC822
-      })
+    private
+
+    def clear_cached_attributes
+      @_attrs   = nil
+      @msg_id   = nil
+      @thr_id   = nil
+      @envelope = nil
+      @message  = nil
+      @flags    = nil
+      @labels   = nil
     end
-    alias_method :raw_message, :message
 
+    def fetch(value)
+      @_attrs ||= begin
+        @gmail.mailbox(@mailbox.name) do
+          @gmail.conn.uid_fetch(uid, PREFETCH_ATTRS)[0]
+        end
+      end
+      @_attrs.attr[value]
+    end
   end # Message
 end # Gmail