postageapp 0.0.0 → 1.0.0

data/.gitignore

@@ -19,3 +19,6 @@ rdoc
 pkg
 
 ## PROJECT::SPECIFIC
+
+test/tmp
+test/log

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2009 Oleg
+Copyright (c) 2009 The Working Group, Inc
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -0,0 +1,176 @@
+PostageApp Gem
+==============
+
+This is the gem used to integrate Ruby apps with PostageApp service.
+Personalized, mass email sending can be offloaded to PostageApp via JSON based API.
+
+Problems, questions, suggestions? Please go to: [help.postageapp.com](http://help.postageapp.com)
+
+Installation
+------------
+
+### Rails 3.x
+Add postageapp gem to your Gemfile:
+    
+    gem 'postageapp'
+    
+Then from the Rails project's root run:
+    
+    bundle install
+    script/rails generate postageapp --api-key PROJECT_API_KEY
+  
+### Rails 2.x
+In config/environment.rb add the following:
+    
+    config.gem 'postageapp'
+    
+Then from the Rails project's root run:
+    
+    rake gems:install
+    rake gems:unpack GEM=postageapp
+    script/generate postageapp --api-key PROJECT_API_KEY
+
+### Sinatra / Rack / Others
+You'll need to install the gem first:
+    
+    $ sudo gem install postageapp
+    
+And then it's as simple as doing something like this:
+    
+    require 'postageapp'
+    
+    PostageApp.configure do |config|
+      config.api_key = 'PROJECT_API_KEY'
+    end
+
+Usage
+-----
+Here's an example of sending a message ([See full API documentation](http://TODO/)):
+  
+    request = PostageApp::Request.new(:send_message, {
+      'headers'     => { 'from'     => 'sender@example.com',
+                         'subject'  => 'Email Subject' },
+      'recipients'  => 'recipient@example.com',
+      'content'     => {
+        'text/plain'  => 'text email content',
+        'text/html'   => 'html email content'
+      }
+    })
+    response = request.send
+  
+`PostageApp::Response` object allows you to check the status:
+  
+    >> response.status
+    => 'ok'
+  
+Alternatively you may use:
+
+    >> response.fail?
+    => false
+    >> response.ok?
+    => true
+  
+Response usually comes back with data:
+  
+    >> response.data
+    => { 'message' => { 'id' => '12345' }}
+    
+### Recipient Override
+Sometimes you don't want to send emails to real people in your application. For that there's an ability to override to what address all emails will be delivered. All you need to do is modify configuration block like this (in Rails projects it's usually found in `RAILS_ROOT/config/initializers/postageapp.rb`):
+
+    PostageApp.configure do |config|
+      config.api_key            = 'PROJECT_API_KEY'
+      config.recipient_override = 'you@example.com' unless Rails.env.production?
+    end
+
+ActionMailer Integration
+------------------------
+You can quickly convert your existing mailers to use PostageApp service by simply changing `class MyMailer < ActionMailer::Base` to `class MyMailer < PostageApp::Mailer`. And don't forget to `require 'postageapp/mailer'`
+
+### Rails 3.x
+
+Here's an example of a mailer in Rails 3 environment:
+
+    require 'postageapp/mailer'
+    
+    class Notifier < PostageApp::Mailer
+    
+      def signup_notification
+        
+        attachments['example.zip'] = File.read('/path/to/example.zip')
+        
+        headers['Special-Header'] = 'SpecialValue'
+        
+        # PostageApp specific elements:
+        postage_template 'example_template'
+        postage_variables 'global_variable' => 'value'
+        
+        mail(
+          :from     => 'test@test.test',
+          :subject  => 'Test Message',
+          :to       => {
+            'recipient_1@example.com' => { 'variable' => 'value' },
+            'recipient_2@example.com' => { 'variable' => 'value' }
+          })
+      end
+    end
+  
+API of previous ActionMailer is partially supported under Rails 3 environment. Please note that it's not 100% integrated, some methods/syntax will not work. You may still define you mailers in this way (but really shouldn't):
+
+    require 'postageapp/mailer'
+    
+    class Notifier < PostageApp::Mailer
+    
+      def signup_notification
+        from    'test@test.test'
+        subject 'Test Email'
+        recipients 'test@test.test'
+      end
+    end
+
+### Rails 2.x
+
+Here's an example of a mailer you'd set in in a Rails 2 environment:
+    
+    require 'postageapp/mailer'
+    
+    class Notifier < PostageApp::Mailer
+      def signup_notification
+        
+        from        'system@example.com'
+        subject     'New Account Information'
+        
+        # Recipients can be in any format API allows.
+        # Here's an example of a hash format
+        recipients  ({
+          'recipient_1@example.com' => { 'variable_name_1' => 'value',
+                                         'variable_name_2' => 'value' },
+          'recipient_2@example.com' => { 'variable_name_1' => 'value',
+                                         'variable_name_2' => 'value' },
+        })
+        
+        attachment  :content_type => 'application/zip',
+                    :filename     => 'example.zip',
+                    :body         => File.read('/path/to/example.zip')
+        
+        # PostageApp specific elements:
+        postage_template 'example_template'
+        postage_variables 'global_variable' => 'value'
+        
+      end
+    end
+    
+Automatic resending in case of failure
+--------------------------------------
+For those ultra rare occasions when api.postageapp.com is not reachable this gem will temporarily store requests and then will attempt to resend them with the next successful connection. In Rails environment it will create a folder: `RAILS_ROOT/tmp/postageapp_failed_requests` and save all failed requests there. On successful resend file for that request will be deleted.
+
+For projects other than Rails you'll need to tell where there project_root is at:
+  
+    PostageApp.configure do |config|
+      config.api_key      = 'PROJECT_API_KEY'
+      config.project_root = "/path/to/your/project"
+    end
+
+Copyright
+---------
+(C) 2010 [The Working Group, Inc](http://www.twg.ca/)

data/Rakefile

@@ -4,23 +4,25 @@ require 'rake'
 begin
   require 'jeweler'
   Jeweler::Tasks.new do |gem|
-    gem.name = "postageapp"
-    gem.summary = "Easier way to send email from web apps"
-    gem.description = "Gem that interfaces with PostageApp.com service to send emails from web apps"
-    gem.email = "oleg@twg.ca"
-    gem.homepage = "http://github.com/theworkinggroup/postageapp-gem"
-    gem.authors = ["Oleg Khabarov, The Working Group Inc"]
-    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+    gem.name        = 'postageapp'
+    gem.summary     = 'Easier way to send email from web apps'
+    gem.description = 'Gem that interfaces with PostageApp.com service to send emails from web apps'
+    gem.email       = 'oleg@twg.ca'
+    gem.homepage    = 'http://github.com/theworkinggroup/postageapp-gem'
+    gem.authors     = ['Oleg Khabarov, The Working Group Inc']
+    
+    gem.add_dependency 'json', '1.2.4' # newer versions crash at the moment
+    gem.add_development_dependency 'mocha', '>= 0.9.8'
   end
   Jeweler::GemcutterTasks.new
 rescue LoadError
-  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+  puts 'Jeweler (or a dependency) not available. Install it with: gem install jeweler'
 end
 
 require 'rake/testtask'
 Rake::TestTask.new(:test) do |test|
   test.libs << 'lib' << 'test'
-  test.pattern = 'test/**/test_*.rb'
+  test.pattern = 'test/**/*_test.rb'
   test.verbose = true
 end
 
@@ -28,12 +30,12 @@ begin
   require 'rcov/rcovtask'
   Rcov::RcovTask.new do |test|
     test.libs << 'test'
-    test.pattern = 'test/**/test_*.rb'
+    test.pattern = 'test/**/*_test.rb'
     test.verbose = true
   end
 rescue LoadError
   task :rcov do
-    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+    abort 'RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov'
   end
 end
 
@@ -44,7 +46,7 @@ task :default => :test
 require 'rake/rdoctask'
 Rake::RDocTask.new do |rdoc|
   version = File.exist?('VERSION') ? File.read('VERSION') : ""
-
+  
   rdoc.rdoc_dir = 'rdoc'
   rdoc.title = "postageapp #{version}"
   rdoc.rdoc_files.include('README*')

data/VERSION

@@ -1 +1 @@
-0.0.0
+1.0.0

data/generators/postageapp/postageapp_generator.rb

@@ -0,0 +1,34 @@
+# Wrapper around rake manifest
+Rails::Generator::Commands::Create.class_eval do
+  def rake(command)
+    system "rake #{command}"
+  end
+end
+
+# Rails 2 Generator
+class PostageappGenerator < Rails::Generator::Base
+  
+  def add_options!(opt)
+    opt.on('-k=key', '--api-key=key') do |value|
+      options[:api_key] = value
+    end
+  end
+  
+  def manifest
+    if !options[:api_key]
+      puts 'Must pass --api-key with API key of your PostageApp.com project'
+      exit
+    end
+    
+    record do |m|
+      m.template 'initializer.rb', 'config/initializers/postageapp.rb', 
+        :assigns    => { :api_key => options[:api_key] },
+        :collision  => :force
+      m.directory 'lib/tasks'
+      m.file 'postageapp_tasks.rake', 'lib/tasks/postageapp_tasks.rake',
+        :collision  => :force
+      m.rake 'postageapp:test'
+    end
+  end
+  
+end

data/generators/postageapp/templates/initializer.rb

@@ -0,0 +1,3 @@
+PostageApp.configure do |config|
+  config.api_key = '<%= api_key %>'
+end

data/generators/postageapp/templates/postageapp_tasks.rake

@@ -0,0 +1,78 @@
+namespace :postageapp do
+  
+  desc 'Verify postageapp gem installation by requesting project info from PostageApp.com'
+  task :test => :environment do 
+    
+    puts "Attempting to contact #{PostageApp.configuration.host} ..."
+    response = PostageApp::Request.new(:get_project_info).send
+    
+    if response.ok?
+      project_name  = response.data['project']['name']
+      project_url   = response.data['project']['url']
+      user_emails   = response.data['project']['users']
+      
+      puts %{
+  Found Project:
+  ----------------------------
+   Name:  #{ project_name }
+    URL:  #{ project_url }
+  Users:  #{ user_emails.keys.join(', ') }
+      }
+        
+      # Sending test email to all users in the project
+      # Most likely a single user if it's a new project
+      puts 'Sending test message to users in the project...'
+      r = send_test_message(user_emails)
+      if r.ok?
+        puts "Message was successfully sent!\n\n"
+        puts 'Your application is ready to use PostageApp!'
+      else
+        puts 'Failed to send test message. Please try again. Check logs if issue persists.'
+        puts 'This was the response:'
+        puts r.to_yaml
+      end
+      
+    else
+      puts 'Failed to fetch information about your project. This was the response:'
+      puts response.to_yaml
+    end
+  end
+  
+end
+
+HTML_MESSAGE = %{
+<h3> Hello {{name}}, </h3>
+<p> This is a html message generated by Postage plugin. </p>
+<p> If you received this message it means that your application is properly configured and is ready to use PostageApp service. </p>
+<p> Thank you, </p>
+<p> The PostageApp Team </p>
+}
+
+TEXT_MESSAGE = %{
+Hello {{name}}
+
+This is a plain text message generated by Postage plugin.
+If you received this message it means that your application is properly configured and is ready to use PostageApp service.
+
+Thank you,
+The PostageApp Team
+}
+
+def send_test_message(recipients)
+  recipients_with_variables = {}
+  recipients.each do |email, name|
+    recipients_with_variables[email] = { 'name' => name }
+  end
+  
+  PostageApp::Request.new(:send_message,
+    :message => {
+      'text/html'  => HTML_MESSAGE,
+      'text/plain' => TEXT_MESSAGE
+    },
+    :recipients => recipients_with_variables,
+    :headers    => {
+      'Subject' => '[PostageApp] Test Message',
+      'From'    => 'no-return@postageapp.com'
+    }
+  ).send
+end

data/lib/generators/postageapp/postageapp_generator.rb

@@ -0,0 +1,27 @@
+require 'rails/generators'
+
+# Rails 3 Generator
+class PostageappGenerator < Rails::Generators::Base
+  
+  class_option :api_key, :aliases => ['-k=value', '--api-key=value'], :type => :string, :desc => 'Your PostageApp API key'
+  
+  def self.source_root
+    @_hoptoad_source_root ||= File.expand_path('../../../../generators/postageapp/templates', __FILE__)
+  end
+  
+  def install
+    if !options[:api_key]
+      puts 'Must pass --api-key with API key of your PostageApp.com project'
+      exit
+    end
+    
+    template 'initializer.rb', 'config/initializers/postageapp.rb'
+    copy_file 'postageapp_tasks.rake', 'lib/tasks/postageapp_tasks.rake'
+    puts run('rake postageapp:test')
+  end
+  
+  def api_key
+    options[:api_key]
+  end
+  
+end

data/lib/postageapp.rb

@@ -0,0 +1,56 @@
+require 'net/http'
+require 'net/https'
+require 'digest'
+require 'logger'
+
+require 'json'
+
+require 'postageapp/utils'
+require 'postageapp/version'
+require 'postageapp/configuration'
+require 'postageapp/logger'
+require 'postageapp/request'
+require 'postageapp/failed_request'
+require 'postageapp/response'
+
+module PostageApp
+  
+  class Error < StandardError ; end
+  
+  class << self
+    
+    # Accessor for the PostageApp::Configuration object
+    attr_accessor :configuration
+    
+    # Call this method to modify your configuration
+    # 
+    # Example:
+    #   PostageApp.configure do |config|
+    #     config.api_key             = '1234567890abcdef'
+    #     config.recipient_override  = 'test@test.test' if Rails.env.staging?
+    #   end
+    def configure
+      self.configuration ||= Configuration.new
+      yield self.configuration
+    end
+    
+    # Logger for the plugin
+    def logger
+      raise Error, 'Need configuration to be set before logger can be used' if !configuration
+      @logger ||= begin
+        configuration.logger || PostageApp::Logger.new(
+          if configuration.project_root
+            FileUtils.mkdir_p(File.join(File.expand_path(configuration.project_root), 'log'))
+            File.join(configuration.project_root, "log/postageapp_#{configuration.environment}.log")
+          else
+            STDOUT
+          end
+        )
+      end
+    end
+    
+  end
+end
+
+# Loading Rails hook
+require 'postageapp/rails' if defined?(Rails)