gmail_cli 0.0.1

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.rvmrc

data/Gemfile

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

data/Guardfile

@@ -0,0 +1,9 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard 'rspec', :version => 2, :all_on_start => false, :all_after_pass => false do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/gmail_cli/(.+)\.rb$})   { |m| "spec/unit/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Paul Gallagher
+
+MIT License
+
+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,91 @@
+# GmailCli
+
+GmailCli packages the key tools and adds a sprinkling of goodness to make it just that much easier
+to write primarily command-line utilities for Gmail/GoogleApps.
+
+The primary use-case it currently covers is accessing Gmail (personal and GoogleApps) via IMAP with OAuth2.
+It solves the problem of ensuring you keep access credentials refreshed without needing manual intervention,
+which is critical if you are building something that is going to run as a scheduled or background process.
+
+This gem doesn't do much of the hard lifting - it is primarily syntactic sugar and packaging for convenience.
+The heavy lifting is provided by:
+* [gmail_xoauth](https://github.com/nfo/gmail_xoauth) which provides OAuth2 support for Google IMAP and SMTP
+* [google-api-ruby-client](https://github.com/google/google-api-ruby-client) which is the official Google API gem providing OAuth2 utilities
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'gmail_cli'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install gmail_cli
+
+## Usage
+
+There are three basic steps required:
+
+1. Create your API project credntials in the [Google APIs console](https://code.google.com/apis/console/), from the "API Access" tab.
+
+2. Authorize your credentials to access a specific account.
+This requires human intervention to explicitly make the approval.
+The authorization is typically for a limited time (1 hour).
+GmailCli provides a command line utility and set of rake tasks to help you do this.
+
+3. Connect to Gmail which will authenticate your credentials.
+GmailCli provides a simple interface to do this, that takes care of resfreshing your credentials
+without manual intervention so you don't have to keep going back to step 2 each time your credntials expire.
+
+
+### How to authorize your OAuth2 credentials - command line approach
+
+  $ gmail_cli authorize
+
+This will prompt you for required information (client_id, client_secret), or you can provide on the command line:
+
+  $ gmail_cli authorize --client_id 'my id' --client_secret 'my secret'
+
+
+### How to authorize your OAuth2 credentials - Rake approach
+
+In your Rakefile, include the line:
+
+  require 'gmail_cli/tasks'
+
+Then from the command line you can:
+
+  $ rake gmail_cli:authorize
+
+This will prompt you for required information (client_id, client_secret), or you can provide on the command line:
+
+  $ rake gmail_cli:authorize client_id='my id' client_secret='my secret'
+
+
+### How to get an OAuth2-authorised IMAP connection to Gmail:
+
+  # how you store or set the credentials Hash is up to you, but it should have the following keys:
+  credentials = {
+    client_id: 'xxxx',
+    client_secret: 'yyyy',
+    refresh_token: 'zzzz'
+  }
+  imap = GmailCli.imap_connection(credentials)
+
+On return, <tt>imap</tt> will either be an open Net::IMAP connection, or an error will have been raised. Possible exceptions include:
+
+...
+
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,25 @@
+require "bundler/gem_tasks"
+require 'rspec'
+require 'rspec/core/rake_task'
+require 'gmail_cli/tasks'
+
+desc "Run all test examples"
+RSpec::Core::RakeTask.new do |t|
+  t.rspec_opts = ["-c", "-f progress"]
+  t.pattern = 'spec/**/*_spec.rb'
+end
+
+task :default => :spec
+
+require 'rdoc/task'
+RDoc::Task.new do |rdoc|
+  rdoc.main = "README.md"
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "Gmail CLI"
+  rdoc.rdoc_files.include('README*', 'lib/**/*.rb')
+end
+
+desc "Open an irb session preloaded with this library"
+task :console do
+  sh "irb -rubygems -I lib -r gmail_cli.rb"
+end

data/bin/gmail_cli

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+$LOAD_PATH.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+
+require 'gmail_cli'
+require 'getoptions'
+
+begin
+  options = GetOptions.new(GmailCli::Shell::OPTIONS)
+  GmailCli::Shell.new(options,ARGV).run
+rescue Exception => e
+  $stderr.puts "That wasn't meant to happen! #{e.message}"
+  GmailCli::Shell.usage
+end
+
+

data/gmail_cli.gemspec

@@ -0,0 +1,32 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'gmail_cli/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "gmail_cli"
+  spec.version       = GmailCli::VERSION
+  spec.authors       = ["Paul Gallagher"]
+  spec.email         = ["gallagher.paul@gmail.com"]
+  spec.description   = %q{A simple toolbox for build utilities that talk to Gmail with OAuth2}
+  spec.summary       = %q{GmailCli packages the key tools and adds a sprinkling of goodness to make it just that much easier to write primarily command-line utilities for Gmail/GoogleApps}
+  spec.homepage      = "https://github.com/evendis/gmail_cli"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency(%q<getoptions>, ["~> 0.3"])
+  spec.add_runtime_dependency(%q<gmail_xoauth>, ["~> 0.4.1"])
+  spec.add_runtime_dependency(%q<google-api-client>, ["~> 0.6.4"])
+
+  spec.add_development_dependency(%q<bundler>, ["> 1.3"])
+  spec.add_development_dependency(%q<rake>, ["~> 0.9.2.2"])
+  spec.add_development_dependency(%q<rspec>, ["~> 2.13.0"])
+  spec.add_development_dependency(%q<rdoc>, ["~> 3.11"])
+  spec.add_development_dependency(%q<guard-rspec>, ["~> 3.0.2"])
+  spec.add_development_dependency(%q<rb-fsevent>, ["~> 0.9.3"])
+
+end

data/lib/gmail_cli/imap.rb

@@ -0,0 +1,72 @@
+require 'net/imap'
+require 'net/http'
+require 'uri'
+require 'gmail_xoauth'
+
+module GmailCli
+
+  # Command: convenience method to return IMAP connection given +options+
+  def self.imap_connection(options={})
+    GmailCli::Imap.new(options).connect!
+  end
+
+  class Imap
+    include GmailCli::LoggerSupport
+
+    attr_accessor :imap, :options, :oauth_options
+
+    def initialize(options={})
+      options = options.dup
+      @oauth_options = {
+        client_id: options.delete(:client_id),
+        client_secret: options.delete(:client_secret),
+        access_token: options.delete(:access_token),
+        refresh_token: options.delete(:refresh_token)
+      }
+      @options = {
+        host: 'imap.gmail.com'
+      }.merge(options)
+      @options[:host_options] ||= {
+        port: 993,
+        ssl: true
+      }
+    end
+
+    def refresh_access_token!
+      oauth_options[:access_token] = GmailCli::Oauth2Helper.new(oauth_options).refresh_access_token!
+    end
+
+    def host
+      options[:host]
+    end
+    def username
+      options[:username]
+    end
+    def host_options
+      options[:host_options]
+    end
+    def oauth_access_token
+      oauth_options[:access_token]
+    end
+
+    def connect!
+      disconnect!
+      refresh_access_token! # we cheat a bit here - refreshing the token every time we get a new connection
+      trace "#{__method__} to host", host
+      self.imap = Net::IMAP.new(host,host_options)
+      trace "imap capabilities", imap.capability
+      imap.authenticate('XOAUTH2', username, oauth_access_token)
+      imap
+    end
+
+    def disconnect!
+      return unless imap
+      trace "calling", __method__
+      imap.close
+      self.imap = nil
+    rescue Exception => e
+      trace "#{__method__} error", e
+    end
+  end
+
+end

data/lib/gmail_cli/logger.rb

@@ -0,0 +1,37 @@
+class GmailCli::Logger
+
+  class << self
+    def log(msg)
+      $stdout.puts "#{Time.now}| #{msg}"
+    end
+    def trace(name,value) ; value ; end
+
+    def set_log_mode(verbose)
+      if verbose
+        class_eval <<-LOGGER_ACTION, __FILE__, __LINE__
+          def self.trace(name,value)
+            $stderr.puts "\#{Time.now}| \#{name}: \#{value.inspect}"
+            value
+          end
+        LOGGER_ACTION
+      else
+        class_eval <<-LOGGER_ACTION, __FILE__, __LINE__
+          def self.trace(name,value) ; value ; end
+        LOGGER_ACTION
+      end
+    end
+
+  end
+
+end
+
+module GmailCli::LoggerSupport
+
+  def trace(name,value)
+    GmailCli::Logger.trace name,value
+  end
+  def log(msg)
+    GmailCli::Logger.log msg
+  end
+
+end

data/lib/gmail_cli/oauth2_helper.rb

@@ -0,0 +1,124 @@
+require 'google/api_client'
+
+class GmailCli::Oauth2Helper
+  include GmailCli::LoggerSupport
+
+  class << self
+    # Command: convenience class method to invoke authorization phase
+    def authorize!(options={})
+      new(options).authorize!
+    rescue Interrupt
+      $stderr.puts "..interrupted."
+    end
+  end
+
+  attr_accessor :client_id, :client_secret
+  attr_accessor :authorization_code, :access_token, :refresh_token
+  attr_accessor :scope, :redirect_uri, :application_name, :application_version
+
+  def initialize(options={})
+    @client_id = options[:client_id]
+    @client_secret = options[:client_secret]
+    @access_token = options[:access_token]
+    @refresh_token = options[:refresh_token]
+    @scope = options[:scope] || 'https://mail.google.com/'
+    @redirect_uri = options[:redirect_uri] || 'urn:ietf:wg:oauth:2.0:oob'
+    @application_name = options[:application_name] || 'gmail_cli'
+    @application_version = options[:application_version] || GmailCli::VERSION
+    trace "#{self.class.name} resolved options", {
+      client_id: client_id, client_secret: client_secret,
+      access_token: access_token, refresh_token: refresh_token,
+      scope: scope, redirect_uri: redirect_uri,
+      application_name: application_name, application_version: application_version
+    }
+  end
+
+  def echo(text)
+    puts text
+  end
+
+  # Command: requests and returns a fresh access_token
+  def refresh_access_token!
+    api_client.authorization.refresh_token = refresh_token
+    response = fetch_refresh_token!
+    # => {"access_token"=>"ya29.AHES6ZRclrR13BePPwPmwdPUtoVqRxJ4fyVKgN1LJzIg-f8", "token_type"=>"Bearer", "expires_in"=>3600}
+    trace "#{__method__} response", response
+    self.access_token = response['access_token']
+  end
+
+  # Command: runs an interactive authorization phase
+  def authorize!
+    echo %(
+Performing Google OAuth2 client authorization
+---------------------------------------------)
+    get_access_token!
+  end
+
+  def api_client
+    @api_client ||= if ensure_provided(:client_id) && ensure_provided(:client_secret) && ensure_provided(:redirect_uri) && ensure_provided(:scope)
+      # Initialize OAuth 2.0 client
+      api_client = Google::APIClient.new(application_name: application_name, application_version: application_version)
+      api_client.authorization.client_id = client_id
+      api_client.authorization.client_secret = client_secret
+      api_client.authorization.redirect_uri = redirect_uri
+      api_client.authorization.scope = scope
+      api_client
+    end
+  end
+
+  def get_access_token!
+    # Request authorization
+    authorization_uri = get_authorization_uri
+    echo %(
+Go to the following URL in a web browser to grant the authorization.
+There you will be able to select specifically which gmail account the authorization is for.
+
+  #{authorization_uri}
+
+When you have done that successfully it will provide a code to enter here:
+)
+    api_client.authorization.code = ensure_provided(:authorization_code)
+    response = fetch_access_token!
+    # => {"access_token"=>"ya29.AHES6ZS_KHUpdO5P0nyvADWf4tL5o8e8C_q5UK0HyyYOF3jw", "token_type"=>"Bearer", "expires_in"=>3600, "refresh_token"=>"1/o4DFZX1_iu_riPiu-OO6FLJ9M8pE5QWmY5DDoUHyOGw"}
+    trace "#{__method__} response", response
+    self.access_token = response['access_token']
+    self.refresh_token = response['refresh_token']
+    echo %(
+Authorization was successful! You can now use this credential to access gmail.
+
+For example, to get an authenticated IMAP connection to the 'name@gmail.com' account:
+
+  credentials = {
+    client_id:     '#{client_id}',
+    client_secret: '#{client_secret}',
+    access_token:  '#{access_token}',
+    refresh_token: '#{refresh_token}',
+    username:      'name@gmail.com'
+  }
+  imap = GmailCli.imap_connection(credentials)
+
+)
+    access_token
+  end
+
+  def get_authorization_uri
+    api_client.authorization.authorization_uri
+  end
+
+  def fetch_access_token!
+    api_client.authorization.fetch_access_token!
+  end
+
+  def fetch_refresh_token!
+    api_client.authorization.refresh!
+  end
+
+  def ensure_provided(key)
+    eval("self.#{key} ||= ask_for_entry('#{key}: ')")
+  end
+
+  def ask_for_entry(prompt)
+    print prompt
+    STDIN.gets.chomp!
+  end
+end

data/lib/gmail_cli/shell.rb

@@ -0,0 +1,71 @@
+# class that groks the command line options and invokes the required task
+class GmailCli::Shell
+
+  # holds the parsed options
+  attr_reader :options
+
+  # holds the remaining command line arguments
+  attr_reader :args
+
+  # initializes the shell with command line argments:
+  #
+  # +options+ is expected to be the hash structure as provided by GetOptions.new(..)
+  #
+  # +args+ is the remaining command line arguments
+  #
+  def initialize(options,args)
+    @options = (options||{}).each{|k,v| {k => v} }
+    @args = args
+    GmailCli::Logger.set_log_mode(options[:verbose])
+  end
+
+  # Command: execute the task according to the options provided on initialisation
+  def run
+    case
+    when args.first =~ /authorize/i
+      authorize
+    else
+      usage
+    end
+  end
+
+  # defines the valid command line options
+  OPTIONS = %w(help verbose client_id:s client_secret:s)
+
+  class << self
+
+    # prints usage/help information
+    def usage
+      $stderr.puts <<-EOS
+
+GmailCli v#{GmailCli::VERSION}
+===================================
+
+Usage:
+  gmail_cli [options] [commands]
+
+Options:
+  -h  | --help           : shows command help
+  -v  | --verbose        : run with verbose
+
+  --client_id "xxxx"     : OAuth2 client_id
+  --client_secret "yyy"  : OAuth2 client_secret
+
+Commands:
+  authorize              : perform Google OAuth2 client authorization
+
+
+EOS
+    end
+  end
+
+  # prints usage/help information
+  def usage
+    self.class.usage
+  end
+
+  def authorize
+    GmailCli::Oauth2Helper.authorize!(options)
+  end
+
+end

data/lib/gmail_cli/tasks.rb

@@ -0,0 +1,18 @@
+namespace :gmail_cli do
+  require 'gmail_cli'
+
+  desc "Perform Google OAuth2 client authorization with client_id=? client_secret=?"
+  task :authorize do |t|
+    options = {
+      client_id: ENV['client_id'],
+      client_secret: ENV['client_secret'],
+      scope: ENV['scope'],
+      redirect_uri: ENV['redirect_uri'],
+      application_name: ENV['application_name'],
+      application_version: ENV['application_version']
+    }
+    GmailCli::Logger.set_log_mode(t.application.options.trace)
+    GmailCli::Oauth2Helper.authorize!(options)
+  end
+
+end

data/lib/gmail_cli/version.rb

@@ -0,0 +1,3 @@
+module GmailCli
+  VERSION = "0.0.1"
+end

data/lib/gmail_cli.rb

@@ -0,0 +1,6 @@
+require "gmail_cli/version"
+require "gmail_cli/logger"
+require "gmail_cli/oauth2_helper"
+require "gmail_cli/shell"
+require "gmail_cli/imap"
+

data/spec/spec_helper.rb

@@ -0,0 +1,25 @@
+require 'gmail_cli'
+
+# Requires supporting files with custom matchers and macros, etc,
+# in ./support/ and its subdirectories.
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each {|f| require f}
+
+RSpec.configure do |config|
+  # == Mock Framework
+  #
+  # If you prefer to use mocha, flexmock or RR, uncomment the appropriate line:
+  #
+  # config.mock_with :mocha
+  # config.mock_with :flexmock
+  # config.mock_with :rr
+  config.mock_with :rspec
+
+  # Remove this line if you're not using ActiveRecord or ActiveRecord fixtures
+  # config.fixture_path = "#{::Rails.root}/spec/fixtures"
+
+  # If you're not using ActiveRecord, or you'd prefer not to run each of your
+  # examples within a transaction, remove the following line or assign false
+  # instead of true.
+  # config.use_transactional_fixtures = true
+
+end

data/spec/unit/imap_spec.rb

@@ -0,0 +1,88 @@
+require 'spec_helper'
+
+describe GmailCli do
+  let(:options) { {} }
+
+  describe "##imap_connection" do
+    subject { GmailCli.imap_connection(options) }
+    it "should return connected GmailCli::Imap" do
+      GmailCli::Imap.any_instance.should_receive(:connect!).and_return('result!')
+      should eql('result!')
+    end
+  end
+
+  describe "::Imap" do
+    let(:imap) { GmailCli::Imap.new(options) }
+    subject { imap }
+
+    describe "#username" do
+      subject { imap.username }
+      it { should be_nil }
+      context "when given in options" do
+        let(:expected) { 'test@test.com' }
+        let(:options) { {username: expected} }
+        it { should eql(expected) }
+      end
+    end
+
+    describe "#host" do
+      subject { imap.host }
+      it { should eql('imap.gmail.com') }
+      context "when given in options" do
+        let(:expected) { 'test.com' }
+        let(:options) { {host: expected} }
+        it { should eql(expected) }
+      end
+    end
+
+    describe "#host_options" do
+      subject { imap.host_options }
+      it { should eql({port: 993, ssl: true}) }
+      context "when given in options" do
+        let(:expected) { {port: 111} }
+        let(:options) { {host_options: expected} }
+        it { should eql(expected) }
+      end
+    end
+
+    describe "#oauth_options" do
+      subject { imap.oauth_options }
+      it { should eql({
+        client_id: nil,
+        client_secret: nil,
+        access_token: nil,
+        refresh_token: nil
+      }) }
+      context "when some given in options" do
+        let(:options) { {client_id: 'abcd'} }
+        it { should eql({
+          client_id: 'abcd',
+          client_secret: nil,
+          access_token: nil,
+          refresh_token: nil
+        }) }
+      end
+      context "when all given in options" do
+        let(:options) { {client_id: 'abcd', client_secret: 'efg', access_token: '123', refresh_token: '456'} }
+        it { should eql({
+          client_id: 'abcd',
+          client_secret: 'efg',
+          access_token: '123',
+          refresh_token: '456'
+        }) }
+        it "should not be included in the options" do
+          imap.options.keys.should_not include(:client_id)
+        end
+        describe "#oauth_access_token" do
+          subject { imap.oauth_access_token }
+          it { should eql('123') }
+        end
+      end
+    end
+
+
+
+  end
+
+end
+

data/spec/unit/logger_spec.rb

@@ -0,0 +1,26 @@
+require 'spec_helper'
+
+describe GmailCli::Logger do
+  let(:logger) { GmailCli::Logger }
+  let(:trace_something) { logger.trace 'somthing', 'bogative' }
+
+  it "should not log when verbose mode not enabled" do
+    $stderr.should_receive(:puts).never
+    trace_something
+  end
+
+  it "should log when verbose mode enabled" do
+    logger.set_log_mode(true)
+    $stderr.should_receive(:puts).and_return(nil)
+    trace_something
+    logger.set_log_mode(false)
+  end
+
+  it "should not log when verbose mode enabled then disabled" do
+    logger.set_log_mode(true)
+    logger.set_log_mode(false)
+    $stderr.should_receive(:puts).never
+    trace_something
+  end
+
+end

data/spec/unit/oauth2_helper_spec.rb

@@ -0,0 +1,168 @@
+require 'spec_helper'
+
+describe GmailCli::Oauth2Helper do
+  let(:resource_class) { GmailCli::Oauth2Helper }
+  let(:instance) { resource_class.new(options) }
+  let(:options) { {} }
+  let(:expected) { 'canary' }
+
+  before do
+    # silence echo
+    resource_class.any_instance.stub(:echo).and_return(nil)
+  end
+
+  describe "##authorize!" do
+    subject { resource_class.authorize!(options) }
+    it "should invoke authorize! on instance" do
+      resource_class.any_instance.should_receive(:authorize!).and_return('result!')
+      should eql('result!')
+    end
+  end
+
+  describe "#client_id" do
+    subject { instance.client_id }
+    it { should be_nil }
+    context "when given in options" do
+      let(:options) { {client_id: expected} }
+      it { should eql(expected) }
+    end
+  end
+
+  describe "#client_secret" do
+    subject { instance.client_secret }
+    it { should be_nil }
+    context "when given in options" do
+      let(:options) { {client_secret: expected} }
+      it { should eql(expected) }
+    end
+  end
+
+  describe "#authorization_code" do
+    subject { instance.authorization_code }
+    it { should be_nil }
+    context "cannot be given in options" do
+      let(:options) { {authorization_code: expected} }
+      it { should be_nil }
+    end
+  end
+
+  describe "#access_token" do
+    subject { instance.access_token }
+    it { should be_nil }
+    context "when given in options" do
+      let(:options) { {access_token: expected} }
+      it { should eql(expected) }
+    end
+  end
+
+  describe "#refresh_token" do
+    subject { instance.refresh_token }
+    it { should be_nil }
+    context "when given in options" do
+      let(:options) { {refresh_token: expected} }
+      it { should eql(expected) }
+    end
+  end
+
+  describe "#scope" do
+    subject { instance.scope }
+    it { should eql('https://mail.google.com/') }
+    context "when given in options" do
+      let(:options) { {scope: expected} }
+      it { should eql(expected) }
+    end
+  end
+
+  describe "#redirect_uri" do
+    subject { instance.redirect_uri }
+    it { should eql('urn:ietf:wg:oauth:2.0:oob') }
+    context "when given in options" do
+      let(:options) { {redirect_uri: expected} }
+      it { should eql(expected) }
+    end
+  end
+
+  describe "#application_name" do
+    subject { instance.application_name }
+    it { should eql('gmail_cli') }
+    context "when given in options" do
+      let(:options) { {application_name: expected} }
+      it { should eql(expected) }
+    end
+  end
+
+  describe "#application_version" do
+    subject { instance.application_version }
+    it { should eql(GmailCli::VERSION) }
+    context "when given in options" do
+      let(:options) { {application_version: expected} }
+      it { should eql(expected) }
+    end
+  end
+
+  describe "#ensure_provided" do
+    let(:key) { :client_id }
+    subject { instance.ensure_provided(key) }
+    context "when value already set" do
+      let(:options) { {client_id: 'set'} }
+      it "should not ask_for_entry when already set" do
+        instance.should_receive(:ask_for_entry).never
+        subject
+      end
+    end
+    context "when value not already set" do
+      it "should ask_for_entry when already set" do
+        instance.should_receive(:ask_for_entry).and_return('got it')
+        subject
+      end
+    end
+  end
+
+  describe "#authorize!" do
+    subject { instance.authorize! }
+    it "should get_access_token" do
+      instance.should_receive(:get_access_token!).and_return(nil)
+      subject
+    end
+  end
+
+  describe "#api_client" do
+    let(:options) { {client_id: 'client_id', client_secret: 'client_secret'} }
+    subject { instance.api_client }
+    it { should be_a(Google::APIClient) }
+  end
+
+  describe "#get_access_token!" do
+    let(:options) { {client_id: 'client_id', client_secret: 'client_secret'} }
+    let(:mock_access_token) { "ya29.AHES6ZS_KHUpdO5P0nyvADWf4tL5o8e8C_q5UK0HyyYOF3jw" }
+    let(:mock_refresh_token) { "ya29.AHES6ZS_KHUpdO5P0nyvADWf4tL5o8e8C_q5UK0HyyYOF3jw" }
+    let(:mock_fetch_access_token_response) { {"access_token"=>mock_access_token, "token_type"=>"Bearer", "expires_in"=>3600, "refresh_token"=>mock_refresh_token} }
+    subject { instance.get_access_token! }
+    it "should orchestrate the fetch_access_token process correctly" do
+      instance.api_client.should be_a(Google::APIClient)
+      instance.should_receive(:get_authorization_uri).and_return('http://here')
+      instance.should_receive(:ensure_provided).with(:authorization_code).and_return('authorization_code')
+      instance.should_receive(:fetch_access_token!).and_return(mock_fetch_access_token_response)
+      subject.should eql(mock_access_token)
+      instance.access_token.should eql(mock_access_token)
+      instance.refresh_token.should eql(mock_refresh_token)
+    end
+  end
+
+  describe "#refresh_access_token!" do
+    let(:options) { {client_id: 'client_id', client_secret: 'client_secret', refresh_token: mock_refresh_token} }
+    let(:mock_access_token) { "ya29.AHES6ZS_KHUpdO5P0nyvADWf4tL5o8e8C_q5UK0HyyYOF3jw" }
+    let(:mock_refresh_token) { "ya29.AHES6ZS_KHUpdO5P0nyvADWf4tL5o8e8C_q5UK0HyyYOF3jw" }
+    let(:mock_fetch_refresh_token_response) { {"access_token"=>mock_access_token, "token_type"=>"Bearer", "expires_in"=>3600} }
+    subject { instance.refresh_access_token! }
+    it "should orchestrate the fetch_access_token process correctly" do
+      instance.api_client.should be_a(Google::APIClient)
+      instance.should_receive(:fetch_refresh_token!).and_return(mock_fetch_refresh_token_response)
+      subject.should eql(mock_access_token)
+      instance.access_token.should eql(mock_access_token)
+      instance.refresh_token.should eql(mock_refresh_token)
+    end
+  end
+
+
+end

data/spec/unit/shell_spec.rb

@@ -0,0 +1,31 @@
+require 'spec_helper'
+require 'getoptions'
+
+describe GmailCli::Shell do
+
+  let(:getoptions) { GetOptions.new(GmailCli::Shell::OPTIONS, options) }
+  let(:shell) { GmailCli::Shell.new(getoptions,argv) }
+
+  before do
+    $stderr.stub(:puts) # silence console feedback chatter
+  end
+
+  describe "#usage" do
+    let(:options) { ['-h'] }
+    let(:argv) { [] }
+    it "should print usage when run" do
+      shell.should_receive(:usage)
+      shell.run
+    end
+  end
+
+  describe "#authorize" do
+    let(:options) { [] }
+    let(:argv) { ["authorize"] }
+    it "should invoke authorize when run" do
+      GmailCli::Oauth2Helper.should_receive(:authorize!)
+      shell.run
+    end
+  end
+
+end

data/spec/unit/tasks_spec.rb

@@ -0,0 +1,21 @@
+require 'spec_helper'
+
+describe "Rake Task gmail_cli:" do
+  require 'rake'
+  require 'gmail_cli/tasks'
+
+  describe "authorize" do
+    let(:task_name) { "gmail_cli:authorize" }
+    let :run_rake_task do
+      Rake::Task[task_name].reenable
+      Rake.application.invoke_task task_name
+    end
+
+    it "should run successfully" do
+      GmailCli::Oauth2Helper.any_instance.should_receive(:authorize!).and_return(nil)
+      expect { run_rake_task }.to_not raise_error
+    end
+
+  end
+
+end

metadata

@@ -0,0 +1,219 @@
+--- !ruby/object:Gem::Specification
+name: gmail_cli
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Paul Gallagher
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-06-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: getoptions
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: gmail_xoauth
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.4.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.4.1
+- !ruby/object:Gem::Dependency
+  name: google-api-client
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.6.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.6.4
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>'
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>'
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.2.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.2.2
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.13.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.13.0
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.11'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.0.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.0.2
+- !ruby/object:Gem::Dependency
+  name: rb-fsevent
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.3
+description: A simple toolbox for build utilities that talk to Gmail with OAuth2
+email:
+- gallagher.paul@gmail.com
+executables:
+- gmail_cli
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- Guardfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/gmail_cli
+- gmail_cli.gemspec
+- lib/gmail_cli.rb
+- lib/gmail_cli/imap.rb
+- lib/gmail_cli/logger.rb
+- lib/gmail_cli/oauth2_helper.rb
+- lib/gmail_cli/shell.rb
+- lib/gmail_cli/tasks.rb
+- lib/gmail_cli/version.rb
+- spec/spec_helper.rb
+- spec/unit/imap_spec.rb
+- spec/unit/logger_spec.rb
+- spec/unit/oauth2_helper_spec.rb
+- spec/unit/shell_spec.rb
+- spec/unit/tasks_spec.rb
+homepage: https://github.com/evendis/gmail_cli
+licenses:
+- MIT
+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: 
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: GmailCli packages the key tools and adds a sprinkling of goodness to make
+  it just that much easier to write primarily command-line utilities for Gmail/GoogleApps
+test_files:
+- spec/spec_helper.rb
+- spec/unit/imap_spec.rb
+- spec/unit/logger_spec.rb
+- spec/unit/oauth2_helper_spec.rb
+- spec/unit/shell_spec.rb
+- spec/unit/tasks_spec.rb