luggage 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: fbf6c643e587287b8d3df07c913163c0c9b56c89
+  data.tar.gz: d7bd6e2bf725860cf8392469f2ca1195358f9863
+SHA512:
+  metadata.gz: c6e39c9d15b0980de7e56c3df266bde5180388b114d145b01b26d66de2b129cde2e019e88dd0bbf3e0557a6b4fb8dce83ddd7fc0759ba88d2733785f68978264
+  data.tar.gz: c070bbb000e6ed0654240cc40c41e015317d6625a07e1c89515ed932770b46b3f74f94c0f29e007087385f940a1d204ceeb5e816a3a2d792c12a726fbf385397

data/.document

@@ -0,0 +1,4 @@
+lib/**/*.rb
+README.rdoc
+ChangeLog.rdoc
+LICENSE.txt

data/.gitignore

@@ -0,0 +1,4 @@
+Gemfile.lock
+html/
+pkg/
+vendor/cache/*.gem

data/.rspec

@@ -0,0 +1 @@
+--colour --format documentation

data/ChangeLog.rdoc

@@ -0,0 +1,4 @@
+=== 0.1.0 / 2012-12-03
+
+* Initial release:
+

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Otherinbox
+
+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.md

@@ -0,0 +1,221 @@
+# Luggage
+
+* [Homepage](https://github.com/otherinbox/luggage#readme)
+* [Issues](https://github.com/otherinbox/luggage/issues)
+
+DSL for interacting with Imap accounts
+
+## Install
+
+Nothing fancy - in you Gemfile;
+
+``` ruby
+gem 'luggage'
+```
+
+That was easy, right?
+
+
+## Before we get started...
+
+Many of the following examples use a DSL/block style syntax.  Most of the object 
+initializers accept a block and do an `instance_eval` on the new object 
+if a block is passed.  These three examples are equivalent:
+
+``` ruby
+Luggage.new :connection => c do
+  mailboxes "INBOX" do
+    message do
+      template "path/to/foo.eml"
+    end.save!
+  end
+end
+```
+
+``` ruby
+f = Luggage.new(:connection => c)
+mb = f.maiboxes["INBOX"]
+m = mb.message(:template => "path/to/foo.eml")
+m.save!
+```
+
+``` ruby
+Luggage.new(:connection => c).mailboxes["INBOX"].message(:template => "path/to/foo.eml").save!
+```
+
+
+## Creating a factory
+
+Factories provide the top-level interface for interacting with IMAP servers.
+All factories require an authenticated `Net::IMAP` instance, however there
+are multiple ways to get there:
+
+### Using an existing Connection
+
+If you have an instance of `Net::IMAP` you can pass it to the constructor as
+`:connection` and the factory will use it.
+
+``` ruby
+f = Luggage.new(:connection => connection)
+```
+
+Keep in mind that the connection needs to be authenticated
+
+### Using an authentication string
+
+`Net::IMAP` natively supports `LOGIN` and `CRAM-MD5` authentication schemes,
+if you want to use either of these you can pass in `:server` and `:authenticate`, 
+the contents of `:authenticate` will be passed to `Net::IMAP#authenticate`.  
+
+``` ruby
+f = Luggage.new(:server => 'imap.aol.com', :authenticate => 'LOGIN user password')
+f = Luggage.new(:server => ['imap.aol.com' 993, true], :authenticate => 'LOGIN user password')
+```
+
+Notice that the value of `:server` will be passed to `Net::IMAP#new`, so the full
+syntax of the initializer is available.  See [the Ruby docs](http://rubydoc.info/stdlib/net/Net/IMAP)
+for more details on auth and intialization
+
+### Using XOauth
+
+Google has implemented XOauth for their IMAP connections.  To use this pass in
+`:server` as before and a token as `:xoauth`
+
+``` ruby
+f = Luggage.new(:server => ['imap.gmail.com', 993, true], :xoauth => token)
+```
+
+See the documentation for you service provider for details on generating that token.
+
+
+## Working with mailboxes
+
+`Luggage#mailboxes` provides an interface to the different mailboxes on your
+remote server.  To access existing mailboxes you can use a couple syntaxes:
+
+``` ruby
+Luggage.new(:connection => c) do
+  mailboxes["SPAM"]   # =>  #<Luggage::Mailbox server: "imap.gmail.com", name: "SPAM">
+  mailboxes("SPAM")   # =>  #<Luggage::Mailbox server: "imap.gmail.com", name: "SPAM">
+  mailboxes[:inbox]   # =>  #<Luggage::Mailbox server: "imap.gmail.com", name: "INBOX">
+  mailboxes[:g_all]   # =>  #<Luggage::Mailbox server: "imap.gmail.com", name: "[Gmail]/All Mail">
+  mailboxes[0]        # =>  #<Luggage::Mailbox server: "imap.gmail.com", name: "INBOX">
+  mailboxes(0)        # =>  #<Luggage::Mailbox server: "imap.gmail.com", name: "INBOX">
+  mailboxes.first     # =>  #<Luggage::Mailbox server: "imap.gmail.com", name: "INBOX">
+  mailboxes           # => [<Luggage::Mailbox server: "imap.gmail.com", name: "SPAM">...]
+  mailboxes[0..10]    # => [<Luggage::Mailbox server: "imap.gmail.com", name: "INBOX">...]
+end
+```
+
+In most cases you can use method call and array/hash index syntax interchangeably.
+Mailboxes come with a couple useful helper methods:
+
+``` ruby
+Luggage.new(:connection => c) do
+  mailboxes["New mailbox"].save!        # Creates the remote mailbox
+  mailboxes["Old and busted"].delete!   # Deletes the remote mailbox
+  mailboxes["Cheshire"].exists?         # Tells you if it exists remotely
+  mailboxes["INBOX"].expunge!           # Permanently deletes any messages marked for deletion
+end
+```
+
+## Querying messages
+
+You can access the messages in a given mailbox through a couple helpers
+
+``` ruby
+Luggage.new(:connection => c) do
+  mailboxes "INBOX" do
+    all                           # Returns an array of all the messages in the mailbox
+    first                         # Returns the first message (sorted by oldest first)
+    where("SINCE", 5.days.ago)    # Executes Net::IMAP#search - see Ruby docs for mor info on search params
+    where(:subject => "FI!")      # Shortcut for 'SUBJECT'
+  end
+end
+```
+
+Querying works somewhat like ActiveRecord scopes, in that you can chain calls to `where` 
+to build up a compound query, which is only executed once you attempt to inspect the results.
+Keep in mind that compound queries are generated by appending each key/value pair into
+big string and sending it to the IMAP server - this isn't SQL
+
+Messages are retrieved somewhat lazily.  The `Message-ID` and `uid` fields are always fetched, 
+but the full body isn't fetched until you try to access a field like `subject` or `body`.
+You can inspect retrieved messages using the same syntax as the [Mail](https://github.com/mikel/mail)
+gem, for instance:
+
+``` ruby
+Luggage.new(:connection => c) do
+  mailboxes "INBOX" do
+    first.subject                 # The email subject
+    first.to                      # TO: field
+    first.headers['Return-Path']  # Random headers
+    first.body                    # Decoded body
+    first.multipart?              # Is this a multi-part email?
+
+    first.flags                   # The flags set on the remote message
+  end
+end
+```
+
+Messages are uniquely identified by their `Message-ID` header, so if you want to access a
+remote email you can fetch its data by creating a new messge instance and passing in the
+message id:
+
+``` ruby
+Luggage.new(:connection => c) do
+  message(:message_id => message_id).reload.flags
+end
+```
+
+See the next section for more details on that `Luggage#message` method...
+
+## Working with messages
+
+`Luggage#message` and `Mailbox#message` provide interfaces for creating messages.  
+
+* If you pass in a `:template` argument, the message will be created using the contents
+of the file at that path.  
+* If you pass an array as `:flags`, the passed flags will be set for the message when 
+it's uploaded to the remote server.
+* A date can be passed as `:date` and will be used as the recieved-at date when the message
+is uploaded.  
+* Any other arguments will be interpreted as properties to be set on the new message.  
+These will be set after the template is read (if provided), allowing
+you to tweak the templates if needed. 
+
+If using the `Luggage` version, a mailbox must be specified as the first argument.
+
+``` ruby
+Luggage.new(:connection => c) do
+  message("INBOX", :template => 'path/to/email.eml').save!
+  
+  mailboxes "INBOX" do
+    message(:template => 'path/to/email.eml').save!
+  
+    message(:template => 'path/to/email.eml', :subject => "Custom subject").save!
+    message do
+      subject "Howdy"
+      body "Partner"
+      from "me@gmail.com"
+      to "you@gmail.com"
+      headers "DKIM-Signature" => "FAIL"
+    end.save!
+  end
+end
+```
+
+_Don't forget to save_.  Cause otherwise it won't get uploaded.
+
+You can also work with existing messages on the server, either by querying for
+them or by instantiating them directly by their message id
+
+``` ruby
+Luggage.new(:connection => c) do
+  mailboxes :g_all do
+    message(:message_id => "<foo@example.com>").exists?     # Does a message with this Message-ID exist in this mailbox?
+    message(:message_id => "<foo@example.com>").reload      # Re-download the content and flags of this message
+    first.delete!                                           # Delete this message (add the 'Deleted' flag)
+  end
+end
+```

data/Rakefile

@@ -0,0 +1,35 @@
+# encoding: utf-8
+
+require 'rubygems'
+
+begin
+  require 'bundler'
+rescue LoadError => e
+  warn e.message
+  warn "Run `gem install bundler` to install Bundler."
+  exit -1
+end
+
+begin
+  Bundler.setup(:development)
+rescue Bundler::BundlerError => e
+  warn e.message
+  warn "Run `bundle install` to install missing gems."
+  exit e.status_code
+end
+
+require 'rake'
+
+require 'rdoc/task'
+RDoc::Task.new do |rdoc|
+  rdoc.title = "luggage"
+end
+task :doc => :rdoc
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new
+
+task :test    => :spec
+task :default => :spec
+
+require "bundler/gem_tasks"

data/lib/luggage/factory.rb

@@ -0,0 +1,63 @@
+module Luggage
+  class Factory
+    attr_reader :connection
+
+    # Factory
+    #
+    # Factories require an instance of Net::IMAP.  Serveral methods are supported:
+    #
+    # Factory.new(:connection => connection)
+    # In this case, `connection` should be an authorized Net::IMAP instance
+    #
+    # Factory.new(:server => "imap.example.com", :authentication => "LOGIN username password")
+    # In this case, we'll build a Net::IMAP instance and attempt to authenticate with the
+    # value of `authentication`.  Net::IMAP supports LOGIN and CRAM-MD5 natively - see below
+    # for xoauth
+    #
+    # Factory.new(:server => "imap.gmail.com", :xoauth => "xoauth token string")
+    # In this case we'll build a Net::IMAP instance and attempt to send a raw XOAUTH authentication
+    # request using the supplied token.
+    #
+    def initialize(args = {}, &block)
+      if args.has_key?(:connection)
+        @connection = args[:connection]
+      elsif args.has_key?(:server) && args.has_key?(:authenticate)
+        @connection = Net::IMAP.new(*Array(args[:server]))
+        @connection.authenticate(*args[:authenticate])
+      elsif args.has_key?(:server) && args.has_key?(:xoauth)
+        @connection = Net::IMAP.new(*Array(args[:server]))
+        @connection.send(:send_command, "AUTHENTICATE XOAUTH #{args[:xoauth]}")
+      else
+        raise ArgumentError, "Imap Connection required."
+      end
+
+      instance_eval &block if block_given?
+    end
+
+    # Factory#message
+    #
+    # Constructs an Message
+    #
+    # `mailbox` can be either a string describing the Imap mailbox the message belongs to
+    # or an instance of Mailbox.
+    #
+    # `args` will be passed to ImapFactorY::Message#new_local - see that method for details
+    #
+    def message(mailbox, args = {}, &block)
+      Message.new_local(connection, mailbox, args, &block)
+    end
+
+    def mailboxes(*args)
+      array = MailboxArray.new(connection)
+      args.empty? ? array : array[*args]
+    end
+
+    def inspect
+      "#<Luggage::Factory server: \"#{host}\">"
+    end
+
+    def host
+      connection.instance_variable_get(:@host)
+    end
+  end
+end

data/lib/luggage/mailbox.rb

@@ -0,0 +1,101 @@
+module Luggage
+  class Mailbox
+    include Enumerable
+
+    attr_reader :connection, :name
+
+    # This provides an interface to a remote Imap mailbox
+    #
+    # `connection` should be an authenticated Net::IMAP
+    #
+    # `name` is the name of the remote mailbox
+    #
+    def initialize(connection, name, &block)
+      raise ArgumentError, "Net::IMAP connection required" unless connection.kind_of?(Net::IMAP)
+      raise ArgumentError, "name required" unless name.present?
+
+      @connection = connection
+      @name = name
+
+      instance_eval &block if block_given?
+    end
+
+    # Constructs an Message whose mailbox will be set to this instance
+    #
+    # `args` will be passed to ImapFactorY::Message#new_local - see that method for details
+    #
+    def message(args = {}, &block)
+      Message.new_local(connection, self, args, &block)
+    end
+
+    # Returns true if this mailbox exists on the remote server, false otherwise
+    #
+    def exists?
+      @exists ||= connection.list("", name).present?
+    end
+
+    # Deletes this mailbox on the remote server
+    #
+    def delete!
+      connection.delete(name)
+      @exists = false
+    end
+
+    # Selects this mailbox for future Imap commands.
+    #
+    def select!
+       connection.select(name)
+    end
+
+    # Creates the mailbox on the remote server if it doesn't exist already
+    #
+    def save!
+      unless exists?
+        connection.create(name)
+      end
+    end
+
+    # Removes 'deleted' messages on the remote server.  Message#delete! marks
+    # messages with the 'Deleted' flag, but leaves them on the server.  This removes
+    # them entirely
+    #
+    def expunge!
+      select!
+      connection.expunge()
+    end
+
+    # Returns an array of Message instances describing all emails in the remote mailbox
+    #
+    def all
+      MailboxQueryBuilder.new(self)
+    end
+
+    # Returns a Message instance describing the first email on the remote mailbox
+    #
+    def first
+      all.first
+    end
+
+    # Iterates over Mailbox#each
+    #
+    def each(&block)
+      all.each(&block)
+    end
+
+    # Filters emails on the remote server
+    #
+    # Returns a MailboxQueryBuilder - see MailboxQueryBuilder#where for usage details
+    #
+    def where(*args)
+      all.where(*args)
+    end
+
+    def inspect
+      "#<Luggage::Mailbox server: \"#{host}\", name: \"#{name}\">"
+    end
+
+    def host
+      connection.instance_variable_get(:@host)
+    end
+  end
+end

data/lib/luggage/mailbox_array.rb

@@ -0,0 +1,58 @@
+module Luggage
+  class MailboxArray
+    attr_reader :connection
+
+    def initialize(connection)
+      @connection = connection
+    end
+
+    def [](*args, &block)
+      case args.first
+      when String
+        mailbox(args.first, &block)
+      when :inbox, :spam, :sent, :trash
+        mailbox(args.first.to_s.upcase, &block)
+      when :g_all
+        mailbox("[Gmail]/All Mail", &block)
+      when :g_sent
+        mailbox("[Gmail]/Sent", &block)
+      when :g_trash
+        mailbox("[Gmail]/Trash", &block)
+      when Symbol
+        mailbox(args.first, &block)
+      when nil
+        mailboxes
+      else
+        super
+      end
+    end
+
+    def method_missing(meth, *args, &block)
+      mailboxes.send(meth, *args, &block)
+    end
+
+    def inspect
+      mailboxes.inspect
+    end
+
+    def host
+      connection.instance_variable_get(:@host)
+    end
+
+    private
+
+    # Cosntructs a Mailbox
+    #
+    # `name` should be a string describing the Imap mailbox's name
+    #
+    def mailbox(name, &block)
+      Mailbox.new(connection, name, &block)
+    end
+
+    def mailboxes
+      connection.list("", "*").map do |result|
+        Mailbox.new(connection, result.name)
+      end
+    end
+  end
+end

data/lib/luggage/mailbox_query_builder.rb

@@ -0,0 +1,77 @@
+module Luggage
+  class MailboxQueryBuilder
+    include Enumerable
+
+    attr_reader :connection, :mailbox, :query
+
+    # Provides an ActiveRecord-style query interface to emails on the remote server
+    #
+    # `mailbox` should be a Mailbox instance describing the remote mailbox to be queried
+    #
+    def initialize(mailbox)
+      raise ArgumentError, "Luggage::Mailbox required" unless mailbox.kind_of?(Mailbox)
+
+      @mailbox = mailbox
+      @connection = mailbox.connection
+      @query = []
+    end
+
+    # Executes the query and yields to each returned result
+    #
+    def each(&block)
+      messages.each(&block)
+    end
+
+    # Builds an Imap search query from the passed `args` hash.  Each key is treated as
+    # a search key, each value is treated as a search value.  Key/value pairs are appended
+    # to an array which will be passed to Net::IMAP#search.  For more details on search
+    # syntax see Ruby std lib docs for Net::IMAP
+    #
+    def where(args = {})
+      @message_ids = nil
+      @messages = nil
+
+      args.each do |key, value|
+        case key.to_sym
+        when :body, :subject, :to, :cc, :from
+          @query += [key.to_s.upcase, value]
+        else
+          @query += [key, value]
+        end
+      end
+      self
+    end
+
+    # Executes the query and returns a slice of the resulting array of messages
+    #
+    def [](*args)
+      messages.[](*args)
+    end
+
+    def messages
+      @messages ||= message_ids.map {|message_id| Message.new(connection, mailbox, :message_id => message_id)}
+    end
+ 
+    def inspect
+      "#<Luggage::MailboxQueryBuilder server: \"#{host}\", mailbox: \"#{mailbox.name}\", query: #{query}>"
+    end
+
+    def host
+      connection.instance_variable_get(:@host)
+    end
+
+    private
+
+    def uids
+      mailbox.select!
+      connection.uid_search(@query.empty? ? "ALL" : @query)
+    end
+
+    def message_ids
+      field = "BODY[HEADER.FIELDS (Message-ID)]"
+      @message_ids ||= connection.uid_fetch(uids, field).map do |resp|
+        $1 if resp[:attr][field] =~ /(<\S*@\S*>)/
+      end.compact
+    end
+  end
+end