things-fetcher 0.1.0

data/.gitignore

@@ -0,0 +1,5 @@
+.rvmrc
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/CHANGELOG

@@ -0,0 +1 @@
+v0.1.0. Initial release.

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in babelyoda.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Andrey Subbotin
+
+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,51 @@
+= things-fetcher
+
+A simple tool to fetch messages from an IMAP folder and create a new to-do item in the Things app for each.
+
+== How It Works
+
+Say, you use Gmail. Say, you want all the mail with +[todo]+ in the subject field to be automatically routed to your Things' Inbox.
+
+1. Create a filter so that all subject mails end up in the same folder/label.
+2. <tt>gem install things-fetcher</tt>
+3. Run <tt>things-fetcher</tt> in Terminal to generate a default config file at <tt>~/.things_fetcher</tt>
+4. Edit the config file at <tt>~/.things_fetcher</tt> to specify your email and so on.
+5. Run <tt>things-fetcher</tt> in Terminal.
+
+Set up a cron task to run <tt>things-fetcher</tt> periodically.
+
+== Configuration
+
+The following options can be specified in the <tt>~/.things_fetcher</tt> file:
+
+[<tt>username</tt>] The username to authenticate with. You must specify one.
+[<tt>password</tt>] The password to authenticate with. Default is to use the Keychain.
+[<tt>server</tt>] The IP address or domain name of the IMAP server. Defaults to +imap.gmail.com+.
+[<tt>port</tt>] The port to connect to. Defaults to +993+.
+[<tt>ssl</tt>] Set to any value to use SSL encryption. Enabled by default.
+[<tt>use_login</tt>] Set to any value to use the LOGIN command instead of AUTHENTICATE. Some servers, like GMail, do not support AUTHENTICATE. Enabled by default.
+[<tt>in_folder</tt>] The name of the folder from which to read incoming mail. Defaults to +Things+.
+[<tt>error_folder</tt>] The name a folder to move mail that causes an error during processing. Defaults to +Things+.
+[<tt>list</tt>] The list in Things to create TODOs in. Defaults to +Inbox+.
+[<tt>tag_names</tt>] The tags to apply to the newly created TODOs. Defaults to +Texted+.
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2012 Andrey Subbotin. See LICENSE for details.
+
+== The IMAP fetching code 
+
+Created by Dan Weinand and Luke Francl. Development supported by {Slantwise Design}[http://slantwisedesign.com].
+Licensed under the terms of the MIT License. Be excellent to each other.
+
+The original repo can be found at: https://github.com/look/fetcher

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bin/things-fetcher

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'things_fetcher'
+
+# Main block
+
+def main
+  config = ThingsFetcher::Config.new("~/.things_fetcher")
+  fetcher = ThingsFetcher::Fetcher.new(config)
+  fetcher.run
+end
+
+# Aux methods
+
+main

data/lib/fetcher/base.rb

@@ -0,0 +1,63 @@
+module Fetcher
+  class Base
+    # Options:
+    # * <tt>:server</tt> - Server to connect to.
+    # * <tt>:username</tt> - Username to use when connecting to server.
+    # * <tt>:password</tt> - Password to use when connecting to server.
+    # * <tt>:receiver</tt> - Receiver object to pass messages to. Assumes the
+    # receiver object has a receive method that takes a message as it's argument
+    #
+    # Additional protocol-specific options implimented by sub-classes
+    #
+    # Example: 
+    #   Fetcher::Base.new(:server => 'mail.example.com',
+    #                     :username => 'pam',
+    #                     :password => 'test',
+    #                     :receiver => IncomingMailHandler)
+    def initialize(options={})
+      %w(server username password receiver).each do |opt|
+        raise ArgumentError, "#{opt} is required" unless options[opt.to_sym]
+        # convert receiver to a Class if it isn't already.
+        if opt == "receiver" && options[:receiver].is_a?(String)
+          options[:receiver] = Kernel.const_get(options[:receiver])
+        end
+          
+        instance_eval("@#{opt} = options[:#{opt}]")
+      end
+    end
+    
+    # Run the fetching process
+    def fetch
+      establish_connection
+      get_messages
+      close_connection
+    end
+    
+    protected
+    
+    # Stub. Should be overridden by subclass.
+    def establish_connection #:nodoc:
+      raise NotImplementedError, "This method should be overridden by subclass"
+    end
+    
+    # Stub. Should be overridden by subclass.
+    def get_messages #:nodoc:
+      raise NotImplementedError, "This method should be overridden by subclass"
+    end
+    
+    # Stub. Should be overridden by subclass.
+    def close_connection #:nodoc:
+      raise NotImplementedError, "This method should be overridden by subclass"
+    end
+    
+    # Send message to receiver object
+    def process_message(message)
+      @receiver.receive(message)
+    end
+    
+    # Stub. Should be overridden by subclass.
+    def handle_bogus_message(message) #:nodoc:
+      raise NotImplementedError, "This method should be overridden by subclass"
+    end
+  end
+end

data/lib/fetcher/imap.rb

@@ -0,0 +1,88 @@
+(RUBY_VERSION < '1.9.0') ? require('system_timer') : require('timeout')
+require_relative 'plain_imap'
+
+module Fetcher
+  class Imap < Base
+    
+    PORT = 143
+    
+    protected
+    
+    # Additional Options:
+    # * <tt>:authentication</tt> - authentication type to use, defaults to PLAIN
+    # * <tt>:port</tt> - port to use (defaults to 143)
+    # * <tt>:ssl</tt> - use SSL to connect
+    # * <tt>:use_login</tt> - use LOGIN instead of AUTHENTICATE to connect (some IMAP servers, like GMail, do not support AUTHENTICATE)
+    # * <tt>:processed_folder</tt> - if set to the name of a mailbox, messages will be moved to that mailbox instead of deleted after processing. The mailbox will be created if it does not exist.
+    # * <tt>:error_folder:</tt> - the name of a mailbox where messages that cannot be processed (i.e., your receiver throws an exception) will be moved. Defaults to "bogus". The mailbox will be created if it does not exist.
+    def initialize(options={})
+      @authentication = options.delete(:authentication) || 'PLAIN'
+      @port = options.delete(:port) || PORT
+      @ssl = options.delete(:ssl)
+      @use_login = options.delete(:use_login)
+      @in_folder = options.delete(:in_folder) || 'INBOX'
+      @processed_folder = options.delete(:processed_folder)
+      @error_folder = options.delete(:error_folder) || 'bogus'
+      super(options)
+    end
+    
+    # Open connection and login to server
+    def establish_connection
+      timeout_call = (RUBY_VERSION < '1.9.0') ? "SystemTimer.timeout_after(15.seconds) do" : "Timeout::timeout(15) do"
+      
+      eval("#{timeout_call}
+              @connection = Net::IMAP.new(@server, @port, @ssl)
+              if @use_login
+                @connection.login(@username, @password)
+              else
+                @connection.authenticate(@authentication, @username, @password)
+              end
+            end")
+    end
+    
+    # Retrieve messages from server
+    def get_messages
+      @connection.select(@in_folder)
+      @connection.uid_search(['ALL']).each do |uid|
+        msg = @connection.uid_fetch(uid,'RFC822').first.attr['RFC822']
+        begin
+          process_message(msg)
+          add_to_processed_folder(uid) if @processed_folder
+        rescue
+          handle_bogus_message(msg)
+        end
+        # Mark message as deleted 
+        @connection.uid_store(uid, "+FLAGS", [:Seen, :Deleted])
+      end
+    end
+    
+    # Store the message for inspection if the receiver errors
+    def handle_bogus_message(message)
+      create_mailbox(@error_folder)
+      @connection.append(@error_folder, message)
+    end
+    
+    # Delete messages and log out
+    def close_connection
+      @connection.expunge
+      @connection.logout
+      begin
+        @connection.disconnect unless @connection.disconnected?
+      rescue
+        Rails.logger.info("Fetcher: Remote closed connection before I could disconnect.")
+      end
+    end
+        
+    def add_to_processed_folder(uid)
+      create_mailbox(@processed_folder)
+      @connection.uid_copy(uid, @processed_folder)
+    end
+    
+    def create_mailbox(mailbox)
+      unless @connection.list("", mailbox)
+        @connection.create(mailbox)
+      end
+    end
+    
+  end
+end

data/lib/fetcher/plain_imap.rb

@@ -0,0 +1,21 @@
+require 'net/imap'
+# add plain as an authentication type...
+# This is taken from:
+# http://svn.ruby-lang.org/cgi-bin/viewvc.cgi/trunk/lib/net/imap.rb?revision=7657&view=markup&pathrev=10966
+
+# Authenticator for the "PLAIN" authentication type.  See
+# #authenticate().
+class PlainAuthenticator
+  def process(data)
+    return "\0#{@user}\0#{@password}"
+  end
+
+  private
+
+  def initialize(user, password)
+    @user = user
+    @password = password
+  end
+end
+
+Net::IMAP.add_authenticator "PLAIN", PlainAuthenticator

data/lib/fetcher.rb

@@ -0,0 +1,21 @@
+module Fetcher
+  # Use factory-style initialization or insantiate directly from a subclass
+  #
+  # Options:
+  # * <tt>:type</tt> - Name of class as a symbol to instantiate
+  #
+  # Other options are the same as Fetcher::Base.new
+  # 
+  # Example:
+  # 
+  # Fetcher.create(:type => :pop) is equivalent to
+  # Fetcher::Pop.new()
+  def self.create(options={})
+    klass = options.delete(:type)
+    raise ArgumentError, 'Must supply a type' unless klass
+    module_eval "#{klass.to_s.capitalize}.new(options)"
+  end
+end
+
+require_relative 'fetcher/base'
+require_relative 'fetcher/imap'

data/lib/keychain.rb

@@ -0,0 +1,23 @@
+# blog post: http://blog.slashpoundbang.com/post/1521530410/accessing-the-os-x-keychain-from-ruby
+
+class KeyChain
+  def self.method_missing(meth, *args)
+    run args.unshift(meth)
+  end
+
+  def self.find_internet_password(*args)
+    # -g: Display the password for the item found
+    output = quiet args.unshift('find-internet-password', '-g') 
+    output[/^password: "(.*)"$/, 1]
+  end
+
+private
+
+  def self.run(*args)
+    `security #{args.join(' ')}`
+  end
+  
+  def self.quiet(*args)
+    run args.unshift('2>&1 >/dev/null')
+  end
+end

data/lib/things_fetcher/config.rb

@@ -0,0 +1,122 @@
+require 'yaml'
+
+require_relative '../keychain'
+
+module ThingsFetcher
+  class Config
+    def initialize(path)
+      super
+
+      @data = default_config
+      @data.merge! load_from_file(path)
+    end
+    
+    def [](key)
+      data.has_key?(key) ? data[key] : send(key.to_s)
+    end
+    
+    def password
+      KeyChain.find_internet_password '-s', data[:server], '-a', data[:username]
+    end
+    
+    private
+      attr_accessor :data
+    
+      def default_config
+        {
+          :server => 'imap.gmail.com',
+          :port => 993,
+          :ssl => true,
+          :use_login => true,
+          :in_folder => 'Things',
+          :error_folder => 'Things',
+          :tag_names => 'Texted',
+          :list => 'Inbox'
+        }        
+      end
+      
+      def load_from_file(path)
+        expanded_path = File.expand_path(path)
+        if File.exists?(expanded_path)
+          loaded_config = YAML::load(File.open(expanded_path))
+          result = {}
+          config_keys.each do |k|
+            if loaded_config.has_key?(k.to_s)
+              result[k] = loaded_config[k.to_s]
+            end
+          end
+          if result.has_key?(:username)
+            result
+          else
+            puts "ERROR: No username specified in the config."
+            puts "       Please edit the config file at: #{expanded_path}"
+            exit 0
+          end
+        else
+          generate_config_file(expanded_path)
+          puts "ERROR: No config file found at: #{expanded_path}"
+          puts "       A new config has been generated."
+          puts "       Please edit."
+          exit 0
+        end
+      end
+      
+      def config_keys
+        [ 
+          :server, 
+          :port, 
+          :ssl, 
+          :use_login, 
+          :in_folder,
+          :error_folder, 
+          :tag_names, 
+          :list, 
+          :username, 
+          :password 
+        ]        
+      end
+      
+      def generate_config_file(path)
+        File.open(path, "w") do |f|
+          f << <<-EOS
+# Any line that starts with a # is a comment.
+# Leave any of the configuration options commented out to use the default value.
+
+# The username to authenticate with.
+# Uncoment and edit the following line.
+# username: email@domain.com
+
+# The password to authenticate with.
+# Leave the following line commented out to you the password stored in the Keychain.
+# Uncomment and edit otherwise.
+# password: somepassword
+          
+# The IP address or domain name of the IMAP server
+# server: imap.gmail.com
+
+# The port to connect to (defaults to the standard port for the type of server)
+# port: 993
+
+# Set to any value to use SSL encryption
+# ssl: true
+
+# Set to any value to use the LOGIN command instead of AUTHENTICATE. 
+# Some servers, like GMail, do not support AUTHENTICATE (IMAP only).
+# use_login: true
+
+# The name of the folder from which to read incoming mail (IMAP only). Defaults to INBOX.
+# in_folder: Things
+
+# The name a folder to move mail that causes an error during processing (IMAP only). 
+# error_folder: Things
+
+# The tags to apply to the newly created TODOs.
+# tag_names: Texted
+
+# The list in Things to create TODOs in.
+# list: Inbox
+EOS
+        end
+      end
+  end
+end

data/lib/things_fetcher/fetcher.rb

@@ -0,0 +1,38 @@
+require_relative '../fetcher'
+require_relative 'mail_handler'
+
+module ThingsFetcher
+  class Fetcher
+    def initialize(config)
+      super
+      @config = config
+    end
+    
+    def run
+      fetcher = ::Fetcher.create(fetcher_options)
+      fetcher.fetch
+    end
+    
+  private
+    attr_accessor :config
+  
+    def fetcher_options
+      {
+        :type => :imap,
+        :receiver => handler,
+        :server => config[:server],
+        :port => config[:port],
+        :ssl => config[:ssl],
+        :use_login => config[:use_login],
+        :username => config[:username],
+        :password => config[:password],
+        :in_folder => config[:in_folder],
+        :error_folder => config[:error_folder]
+      }      
+    end
+    
+    def handler
+      ThingsFetcher::MailHandler.new(config)      
+    end
+  end
+end

data/lib/things_fetcher/mail_handler.rb

@@ -0,0 +1,29 @@
+require 'appscript'
+require 'mail'
+require 'osax'
+
+module ThingsFetcher
+  class MailHandler
+    def initialize(config)
+      super
+      @config = config
+    end
+    
+    def receive(data)
+      msg = Mail.read_from_string(data)
+      make_todo msg.subject
+    end
+  
+    private
+      include Appscript
+      include OSAX
+      
+      attr_accessor :config
+  
+      def make_todo(name)
+        things = app("Things")
+        todo = things.make(:new => :to_do, :at => things.lists[config[:list]], :with_properties => { :name => name })
+        todo.tag_names.set config[:tag_names]
+      end
+  end
+end

data/lib/things_fetcher/version.rb

@@ -0,0 +1,3 @@
+module ThingsFetcher
+  VERSION = "0.1.0"
+end

data/lib/things_fetcher.rb

@@ -0,0 +1,2 @@
+require_relative 'things_fetcher/config'
+require_relative 'things_fetcher/fetcher'

data/things-fetcher.gemspec

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "things_fetcher/version"
+
+Gem::Specification.new do |s|
+  s.name        = "things-fetcher"
+  s.version     = ThingsFetcher::VERSION
+  s.authors     = ["Andrey Subbotin"]
+  s.email       = ["andrey@subbotin.me"]
+  s.homepage    = "http://github.com/eploko/things-fetcher"
+  s.summary     = "Imports to-dos from IMAP to Things.app"
+  s.description = "A simple daemon to periodically check an IMAP folder and create a new to-dos in the Things app for each new message."
+  
+  s.rubyforge_project = "things-fetcher"
+
+  s.files         = `git ls-files`.split("\n")
+  s.require_paths = ["lib"]
+  
+  s.executables = ["things-fetcher"]
+  s.default_executable = ["things-fetcher"]
+  s.extra_rdoc_files = [
+    "LICENSE",
+    "README.rdoc"
+  ]
+  
+  s.add_development_dependency "rake"
+  
+  s.add_runtime_dependency "mail"
+  s.add_runtime_dependency "rb-appscript"
+end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: things-fetcher
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Andrey Subbotin
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-05-19 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &70233798421180 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70233798421180
+- !ruby/object:Gem::Dependency
+  name: mail
+  requirement: &70233798420760 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70233798420760
+- !ruby/object:Gem::Dependency
+  name: rb-appscript
+  requirement: &70233798420340 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70233798420340
+description: A simple daemon to periodically check an IMAP folder and create a new
+  to-dos in the Things app for each new message.
+email:
+- andrey@subbotin.me
+executables:
+- things-fetcher
+extensions: []
+extra_rdoc_files:
+- LICENSE
+- README.rdoc
+files:
+- .gitignore
+- CHANGELOG
+- Gemfile
+- LICENSE
+- README.rdoc
+- Rakefile
+- bin/things-fetcher
+- lib/fetcher.rb
+- lib/fetcher/base.rb
+- lib/fetcher/imap.rb
+- lib/fetcher/plain_imap.rb
+- lib/keychain.rb
+- lib/things_fetcher.rb
+- lib/things_fetcher/config.rb
+- lib/things_fetcher/fetcher.rb
+- lib/things_fetcher/mail_handler.rb
+- lib/things_fetcher/version.rb
+- things-fetcher.gemspec
+homepage: http://github.com/eploko/things-fetcher
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: things-fetcher
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Imports to-dos from IMAP to Things.app
+test_files: []